# 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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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"}}}}},"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"}}}}}}}},"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":[{"additionalProperties":false,"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"},{"additionalProperties":false,"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"},{"additionalProperties":false,"required":["addresses","destination","username","password"],"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={{"201":{"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."},"is_concurrent":{"type":"boolean","example":false,"default":false,"description":"Whether the events observed by this integration are processed concurrently."},"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":[{"additionalProperties":false,"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"},{"additionalProperties":false,"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"},{"additionalProperties":false,"required":["addresses","destination","username","password"],"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","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier of the deleted 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"]}}}}}}}},"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."},"is_concurrent":{"type":"boolean","example":false,"default":false,"description":"Whether the events observed by this integration are processed concurrently."},"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":[{"additionalProperties":false,"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"},{"additionalProperties":false,"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"},{"additionalProperties":false,"required":["addresses","destination","username","password"],"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-log`.","type":"string","example":"integration-log","enum":["integration-log"],"default":"integration-log"},"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."},"processing_time":{"type":"number","format":"float","example":30.0006,"description":"The time taken to process the delivery attempt, in seconds, rounded to four decimal places."},"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":"integration-job"}}}}}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date and time the integration log was created.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}}}}}},"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."},"is_concurrent":{"type":"boolean","example":false,"default":false,"description":"Whether the events observed by this integration are processed concurrently."},"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":[{"additionalProperties":false,"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"},{"additionalProperties":false,"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"},{"additionalProperties":false,"required":["addresses","destination","username","password"],"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-log`.","type":"string","example":"integration-log","enum":["integration-log"],"default":"integration-log"},"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."},"processing_time":{"type":"number","format":"float","example":30.0006,"description":"The time taken to process the delivery attempt, in seconds, rounded to four decimal places."},"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":"integration-job"}}}}}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date and time the integration log was created.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}}}}}},"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-log`.","type":"string","example":"integration-log","enum":["integration-log"],"default":"integration-log"},"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."},"processing_time":{"type":"number","format":"float","example":30.0006,"description":"The time taken to process the delivery attempt, in seconds, rounded to four decimal places."},"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":"integration-job"}}}}}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date and time the integration log was created.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}}}}}},"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."},"is_concurrent":{"type":"boolean","example":true,"description":"Whether the events observed by this integration are processed concurrently. Setting this to `false` is not supported for integrations that already process events concurrently."},"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":[{"additionalProperties":false,"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"},{"additionalProperties":false,"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"},{"additionalProperties":false,"required":["addresses","destination","username","password"],"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."},"is_concurrent":{"type":"boolean","example":false,"default":false,"description":"Whether the events observed by this integration are processed concurrently."},"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":[{"additionalProperties":false,"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"},{"additionalProperties":false,"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"},{"additionalProperties":false,"required":["addresses","destination","username","password"],"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","custom_user_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","custom_user_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","custom_user_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"]},"catalog_search":{"type":"string","description":"The access level for Catalog Search.","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"]},"content_and_pages":{"type":"string","description":"The access level for Content and Pages.","enum":["none","view","manage"]},"currencies":{"type":"string","description":"The access level for Currencies.","enum":["none","view","manage"]},"custom_actions":{"type":"string","description":"The access level for Custom Actions.","enum":["none","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"]},"inventories":{"type":"string","description":"The access level for Inventories.","enum":["none","view","manage"]},"legacy_catalogs":{"type":"string","description":"The access level for Legacy Catalogs.","enum":["none","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"]}},"title":"AccessLevels"},"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","custom_user_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"]},"catalog_search":{"type":"string","description":"The access level for Catalog Search.","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"]},"content_and_pages":{"type":"string","description":"The access level for Content and Pages.","enum":["none","view","manage"]},"currencies":{"type":"string","description":"The access level for Currencies.","enum":["none","view","manage"]},"custom_actions":{"type":"string","description":"The access level for Custom Actions.","enum":["none","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"]},"inventories":{"type":"string","description":"The access level for Inventories.","enum":["none","view","manage"]},"legacy_catalogs":{"type":"string","description":"The access level for Legacy Catalogs.","enum":["none","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"]}},"title":"AccessLevels"},"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","custom_user_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"},"search_profile_slug":{"type":"string","description":"Optional slug of a Catalog Search profile to apply when this rule is selected for a shopper.\nThis is configuration on the rule (same role as `pricebook_ids`), not a shopper-context matching dimension.\n","example":"vip-search","nullable":true}},"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"},"search_profile_slug":{"type":"string","description":"Optional slug of a Catalog Search profile to apply when this rule is selected for a shopper.\nThis is configuration on the rule (same role as `pricebook_ids`), not a shopper-context matching dimension.\nOmitted from responses when unset.\n","example":"vip-search","x-omitempty":true,"nullable":true}},"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",