> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/api/catalog-api/catalog.md).

# Catalog

Search the catalog index. `/catalog_items` answers for every record type, and `/published_catalog_items` answers for the published copy of the types that publish. Both take a `record_type`, filter by path, tag and attribute, and paginate.

Use these endpoints to find records that you cannot yet name: every offer with a tag, the pages that show a label, the products changed since a date. They read a search index, so they carry large result sets, and they can lag a write by some seconds.

To read one record that you can already name, use Catalog Management.

## Get Catalog Items

> Lists the records of one type from the catalog index, offers, products, add-ons, pages, segments or discounts, and answers with the working copy of each one. It supersedes \`/add\_ons\`, \`/offers/v2\`, \`/pages\`, \`/products\` and \`/segments\`, which each answer for one type from the same index.\
> \
> \`record\_type\` selects the type. Every catalog type is available. Filter further by \`path\`, \`tags\`, \`referencedLabel\` and any \`attributes.\*\` value, and page through the result with the \`opt.\*\` parameters.\
> \
> Use this endpoint to find records: every offer with a tag, the products changed since a date, the pages that show a label. Use \`/published\_catalog\_items\` for the published copy instead of the working copy.\
> \
> Do not use this endpoint to read back a record that you just wrote. The index can lag a write by some seconds. \`GET /limio/catalogs/1/items/{path}\` reads the catalog itself, so it answers at once and answers with the record exactly as it is stored.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Catalog","description":"Search the catalog index. `/catalog_items` answers for every record type, and `/published_catalog_items` answers for the published copy of the types that publish. Both take a `record_type`, filter by path, tag and attribute, and paginate.\n\nUse these endpoints to find records that you cannot yet name: every offer with a tag, the pages that show a label, the products changed since a date. They read a search index, so they carry large result sets, and they can lag a write by some seconds.\n\nTo read one record that you can already name, use Catalog Management."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"parameters":{"catalogRecordType":{"in":"query","name":"record_type","required":true,"description":"The record type to retrieve. Each type answers from its own tree in the catalog index.","schema":{"type":"string","enum":["add_on","discount","family","offer","page","product","segment","template"]}},"catalogId":{"in":"query","name":"id","description":"Filter items by Elasticsearch document ID.","schema":{"type":"string"}},"path":{"in":"query","name":"path","description":"Filter by the exact catalog path of the item, e.g. `/offers/2024 Summer Campaign` or `/pages/Homepage`.","schema":{"type":"string"}},"referencedLabel":{"in":"query","name":"referencedLabel","description":"Filter items by referenced label.","schema":{"type":"string"}},"reducedData":{"in":"query","name":"reducedData","description":"Set to `true` to leave out a fixed set of heavy display attributes (assets, attachments, checkout, offer features and styling) and the attributes of each expanded product. It is not a projection: it does not take a list of fields, and it does not remove a large attribute array such as `allowed_countries`. Use it to trim a response, not to choose what a response holds.","schema":{"type":"boolean"}},"optPageSize":{"in":"query","name":"opt.pageSize","description":"Number of items per page (default 50, maximum 160). The response size limit is 6 MB, so use smaller page sizes with `queryMore` pagination when retrieving large datasets. Note: this parameter cannot be used in combination with `opt.all=true` — once `opt.all` is set, the page size cannot be increased.","schema":{"type":"integer","default":50}},"optModifiedAfter":{"in":"query","name":"opt.modifiedAfter","description":"Filter items modified after the indicated date or date-time (ISO-date format, i.e '2020-12-01' or '2020-12-01T16:00:00Z')","schema":{"type":"string","format":"date-time"}},"optAll":{"in":"query","name":"opt.all","description":"Set to `true` to enable cursor-based pagination. When enabled, the response includes a `queryMore` object with `from` and `alias` fields that can be passed to subsequent requests to retrieve the next page. A maximum of 100 items will be returned per page when active.","schema":{"type":"boolean","default":false}},"optQueryMoreFrom":{"in":"query","name":"opt.queryMoreFrom","description":"The From Hash for the query more functionality. Use it to fetch next page of the query (obtained from queryMore.from in the response)","schema":{"type":"string"}},"optQueryMoreAlias":{"in":"query","name":"opt.queryMoreAlias","description":"The Alias for the query more functionality. Use it to fetch next page of the query (obtained from queryMore.alias in the response)","schema":{"type":"string"}},"attributes":{"in":"query","name":"attributes.YOUR_ATTRIBUTE_HERE","description":"To query with attributes, replace 'YOUR_ATTRIBUTE_HERE' with your attribute. Attributes are defined by your templates.","schema":{"type":"string"}}},"schemas":{"ElasticOffer":{"properties":{"id":{"type":"string","description":"Offer id in the Elastic index"},"name":{"type":"string","description":"Offer name"},"parent_path":{"type":"string","description":"Parent Path"},"path":{"type":"string","description":"Path to the offer"},"data":{"type":"object","description":"Data attached to offer","properties":{"attributes":{"type":"object"},"price":{"type":"array","description":"Prices of offer","items":{"type":"object","description":"Price item","properties":{"attributes":{"type":"object"},"name":{"type":"string","description":"Charge name"},"label":{"type":"string","description":"Label for charge"},"currencyCode":{"type":"string","description":"Currency of charge"},"value":{"type":"string","description":"Value of charge"},"type":{"type":"string","description":"Pricing type"},"trigger":{"type":"string","description":"Trigger for the charge"},"repeat_interval":{"type":"integer","description":"Number of repeat_interval_type between charges"},"repeat_interval_type":{"type":"string","description":"The unit between charges"},"repeat_count":{"type":"integer","description":"The number of times the charge will be repeated"},"delay_trigger":{"type":"string","description":"Delay to charge trigger"},"delay_interval":{"type":"integer","description":"Number of delay_interval_type that charge will be delayed"},"delay_interval_type":{"type":"string","description":"The unit charge will be delayed"}}}},"products":{"type":"array","description":"Products attached to offer","items":{"$ref":"#/components/schemas/ElasticProduct"}},"segments":{"type":"array","description":"Segments attached to offer","items":{"type":"string","description":"Path to segment"}},"tags":{"type":"array","description":"Tags attached to campaign","items":{"type":"string","description":"tag path"}},"status":{"type":"string","description":"Offer status"},"description":{"type":"string","description":"Offer description"},"validFrom":{"type":"string","description":"Date offer is valid from"},"validTo":{"type":"string","description":"Date offer is valid until"}}}}},"ElasticProduct":{"type":"object","properties":{"id":{"type":"string","description":"Product id in the Elastic index"},"name":{"type":"string","description":"Name of product"},"parent_path":{"type":"string","description":"Parent Path"},"path":{"type":"string","description":"Product path"},"data":{"type":"object","properties":{"attributes":{"type":"object","description":"Attributes for product"},"baseTemplate":{"type":"string","description":"Template for product attributes"}}}}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/catalog_items":{"get":{"operationId":"getCatalogItems","summary":"Get Catalog Items","tags":["Catalog"],"description":"Lists the records of one type from the catalog index, offers, products, add-ons, pages, segments or discounts, and answers with the working copy of each one. It supersedes `/add_ons`, `/offers/v2`, `/pages`, `/products` and `/segments`, which each answer for one type from the same index.\n\n`record_type` selects the type. Every catalog type is available. Filter further by `path`, `tags`, `referencedLabel` and any `attributes.*` value, and page through the result with the `opt.*` parameters.\n\nUse this endpoint to find records: every offer with a tag, the products changed since a date, the pages that show a label. Use `/published_catalog_items` for the published copy instead of the working copy.\n\nDo not use this endpoint to read back a record that you just wrote. The index can lag a write by some seconds. `GET /limio/catalogs/1/items/{path}` reads the catalog itself, so it answers at once and answers with the record exactly as it is stored.","parameters":[{"$ref":"#/components/parameters/catalogRecordType"},{"$ref":"#/components/parameters/catalogId"},{"$ref":"#/components/parameters/path"},{"$ref":"#/components/parameters/referencedLabel"},{"$ref":"#/components/parameters/reducedData"},{"$ref":"#/components/parameters/optPageSize"},{"$ref":"#/components/parameters/optModifiedAfter"},{"$ref":"#/components/parameters/optAll"},{"$ref":"#/components/parameters/optQueryMoreFrom"},{"$ref":"#/components/parameters/optQueryMoreAlias"},{"$ref":"#/components/parameters/attributes"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"object","description":"Total number of matching records in the index.","properties":{"value":{"type":"number","description":"The number of records found"},"relation":{"type":"string","description":"How value relates to the true total: eq (exact) or gte (lower bound)"}}},"items":{"type":"array","description":"The catalog items matching the query.","items":{"$ref":"#/components/schemas/ElasticOffer"}},"queryMore":{"type":"object","description":"Pagination cursor for fetching additional results.","properties":{"from":{"type":"string"},"alias":{"type":"string"}}},"commitId":{"type":"string","description":"The commit ID of the index that was queried."}}}}}},"400":{"description":"Bad request. Returned when query parameters fail validation, e.g. missing `record_type`."},"401":{"$ref":"#/components/responses/401ApplicationResponse"}}}}}}
```

## Get Published Catalog Items

> Searches the published index and answers with the live copy of each record. A record appears here only after a publish, so this is the endpoint that answers what a customer sees.\
> \
> Only the types that publish are available: \`add\_on\`, \`offer\` and \`discount\`. It takes the same filters and paging as \`/catalog\_items\`.\
> \
> Use \`/catalog\_items\` for the working copy, which includes records that no publish has made live. Use \`GET /limio/catalogs/1/items/{path}\` to read one record that you can name, exactly as it is stored.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Catalog","description":"Search the catalog index. `/catalog_items` answers for every record type, and `/published_catalog_items` answers for the published copy of the types that publish. Both take a `record_type`, filter by path, tag and attribute, and paginate.\n\nUse these endpoints to find records that you cannot yet name: every offer with a tag, the pages that show a label, the products changed since a date. They read a search index, so they carry large result sets, and they can lag a write by some seconds.\n\nTo read one record that you can already name, use Catalog Management."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"parameters":{"publishedCatalogRecordType":{"in":"query","name":"record_type","required":true,"description":"The type of published item to retrieve. Only publishable types are accepted.","schema":{"type":"string","enum":["add_on","offer","discount"]}},"catalogId":{"in":"query","name":"id","description":"Filter items by Elasticsearch document ID.","schema":{"type":"string"}},"path":{"in":"query","name":"path","description":"Filter by the exact catalog path of the item, e.g. `/offers/2024 Summer Campaign` or `/pages/Homepage`.","schema":{"type":"string"}},"referencedLabel":{"in":"query","name":"referencedLabel","description":"Filter items by referenced label.","schema":{"type":"string"}},"reducedData":{"in":"query","name":"reducedData","description":"Set to `true` to leave out a fixed set of heavy display attributes (assets, attachments, checkout, offer features and styling) and the attributes of each expanded product. It is not a projection: it does not take a list of fields, and it does not remove a large attribute array such as `allowed_countries`. Use it to trim a response, not to choose what a response holds.","schema":{"type":"boolean"}},"optPageSize":{"in":"query","name":"opt.pageSize","description":"Number of items per page (default 50, maximum 160). The response size limit is 6 MB, so use smaller page sizes with `queryMore` pagination when retrieving large datasets. Note: this parameter cannot be used in combination with `opt.all=true` — once `opt.all` is set, the page size cannot be increased.","schema":{"type":"integer","default":50}},"optModifiedAfter":{"in":"query","name":"opt.modifiedAfter","description":"Filter items modified after the indicated date or date-time (ISO-date format, i.e '2020-12-01' or '2020-12-01T16:00:00Z')","schema":{"type":"string","format":"date-time"}},"optAll":{"in":"query","name":"opt.all","description":"Set to `true` to enable cursor-based pagination. When enabled, the response includes a `queryMore` object with `from` and `alias` fields that can be passed to subsequent requests to retrieve the next page. A maximum of 100 items will be returned per page when active.","schema":{"type":"boolean","default":false}},"optQueryMoreFrom":{"in":"query","name":"opt.queryMoreFrom","description":"The From Hash for the query more functionality. Use it to fetch next page of the query (obtained from queryMore.from in the response)","schema":{"type":"string"}},"optQueryMoreAlias":{"in":"query","name":"opt.queryMoreAlias","description":"The Alias for the query more functionality. Use it to fetch next page of the query (obtained from queryMore.alias in the response)","schema":{"type":"string"}},"attributes":{"in":"query","name":"attributes.YOUR_ATTRIBUTE_HERE","description":"To query with attributes, replace 'YOUR_ATTRIBUTE_HERE' with your attribute. Attributes are defined by your templates.","schema":{"type":"string"}}},"schemas":{"ElasticOffer":{"properties":{"id":{"type":"string","description":"Offer id in the Elastic index"},"name":{"type":"string","description":"Offer name"},"parent_path":{"type":"string","description":"Parent Path"},"path":{"type":"string","description":"Path to the offer"},"data":{"type":"object","description":"Data attached to offer","properties":{"attributes":{"type":"object"},"price":{"type":"array","description":"Prices of offer","items":{"type":"object","description":"Price item","properties":{"attributes":{"type":"object"},"name":{"type":"string","description":"Charge name"},"label":{"type":"string","description":"Label for charge"},"currencyCode":{"type":"string","description":"Currency of charge"},"value":{"type":"string","description":"Value of charge"},"type":{"type":"string","description":"Pricing type"},"trigger":{"type":"string","description":"Trigger for the charge"},"repeat_interval":{"type":"integer","description":"Number of repeat_interval_type between charges"},"repeat_interval_type":{"type":"string","description":"The unit between charges"},"repeat_count":{"type":"integer","description":"The number of times the charge will be repeated"},"delay_trigger":{"type":"string","description":"Delay to charge trigger"},"delay_interval":{"type":"integer","description":"Number of delay_interval_type that charge will be delayed"},"delay_interval_type":{"type":"string","description":"The unit charge will be delayed"}}}},"products":{"type":"array","description":"Products attached to offer","items":{"$ref":"#/components/schemas/ElasticProduct"}},"segments":{"type":"array","description":"Segments attached to offer","items":{"type":"string","description":"Path to segment"}},"tags":{"type":"array","description":"Tags attached to campaign","items":{"type":"string","description":"tag path"}},"status":{"type":"string","description":"Offer status"},"description":{"type":"string","description":"Offer description"},"validFrom":{"type":"string","description":"Date offer is valid from"},"validTo":{"type":"string","description":"Date offer is valid until"}}}}},"ElasticProduct":{"type":"object","properties":{"id":{"type":"string","description":"Product id in the Elastic index"},"name":{"type":"string","description":"Name of product"},"parent_path":{"type":"string","description":"Parent Path"},"path":{"type":"string","description":"Product path"},"data":{"type":"object","properties":{"attributes":{"type":"object","description":"Attributes for product"},"baseTemplate":{"type":"string","description":"Template for product attributes"}}}}}},"responses":{"401ApplicationResponse":{"description":"Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique identifier of the request"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/published_catalog_items":{"get":{"operationId":"getPublishedCatalogItems","summary":"Get Published Catalog Items","tags":["Catalog"],"description":"Searches the published index and answers with the live copy of each record. A record appears here only after a publish, so this is the endpoint that answers what a customer sees.\n\nOnly the types that publish are available: `add_on`, `offer` and `discount`. It takes the same filters and paging as `/catalog_items`.\n\nUse `/catalog_items` for the working copy, which includes records that no publish has made live. Use `GET /limio/catalogs/1/items/{path}` to read one record that you can name, exactly as it is stored.","parameters":[{"$ref":"#/components/parameters/publishedCatalogRecordType"},{"$ref":"#/components/parameters/catalogId"},{"$ref":"#/components/parameters/path"},{"$ref":"#/components/parameters/referencedLabel"},{"$ref":"#/components/parameters/reducedData"},{"$ref":"#/components/parameters/optPageSize"},{"$ref":"#/components/parameters/optModifiedAfter"},{"$ref":"#/components/parameters/optAll"},{"$ref":"#/components/parameters/optQueryMoreFrom"},{"$ref":"#/components/parameters/optQueryMoreAlias"},{"$ref":"#/components/parameters/attributes"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"object","description":"Total number of matching records in the index.","properties":{"value":{"type":"number","description":"The number of records found"},"relation":{"type":"string","description":"How value relates to the true total: eq (exact) or gte (lower bound)"}}},"items":{"type":"array","description":"The published catalog items matching the query.","items":{"$ref":"#/components/schemas/ElasticOffer"}},"queryMore":{"type":"object","description":"Pagination cursor for fetching additional results.","properties":{"from":{"type":"string"},"alias":{"type":"string"}}},"commitId":{"type":"string","description":"The commit ID of the index that was queried."}}}}}},"400":{"description":"Bad request. Returned when query parameters fail validation, e.g. non-publishable record_type or missing required parameters."},"401":{"$ref":"#/components/responses/401ApplicationResponse"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.limio.com/api/catalog-api/catalog.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.