> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/basket-offers/models.md).

# Models

## The DateTimeRangeObject object

```json
{"openapi":"3.0.3","info":{"title":"Promotions API","version":"1.0.0"},"components":{"schemas":{"DateTimeRangeObject":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Start of the datetime window (ISO 8601)"},"end":{"type":"string","format":"date-time","description":"End of the datetime window (ISO 8601). Must be after `start`."}}}}}}
```

## The BasketOfferSchedulerRequest object

```json
{"openapi":"3.0.3","info":{"title":"Promotions API","version":"1.0.0"},"components":{"schemas":{"BasketOfferSchedulerRequest":{"type":"object","description":"Configuration for automated scheduling of the offer's active windows.\nAt least one of `cron` (non-empty) or `inclusions` must be provided.\n\n**Mode A** — specific-minute cron: `cron` has a concrete minute value (e.g. `0` or `30`).\n`duration` is **required** and defines how long the offer stays active after each trigger.\n\n**Mode B** — minute-wildcard cron: `cron` minute field is `*` (e.g. `* 9-17 * * 1-5`).\n`duration` must be omitted or `null`; the offer is active for every minute matched by the expression.\n\n**Inclusions-only** — `cron` is an empty string `\"\"` and `inclusions` provides the explicit windows directly.\n","properties":{"cron":{"type":"string","description":"5-field cron expression (`minute hour day-of-month month day-of-week`).\nPass an empty string `\"\"` to use inclusions-only mode.\n"},"duration":{"type":"string","nullable":true,"description":"ISO 8601 duration (e.g. `PT4H`, `PT30M`). **Required** when `cron` uses a specific\nminute value (Mode A). Must be `null` or omitted when the cron minute field is `*`\n(Mode B). Ignored when `cron` is an empty string.\n"},"inclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Explicit datetime windows added on top of any cron-generated windows.\nWindows must not overlap each other.\n"},"exclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Datetime windows subtracted from all candidate windows (cron-generated and included).\nUse to block out holidays or maintenance periods.\n"},"timezone":{"type":"string","description":"IANA timezone name used to interpret the cron fields. Defaults to `UTC` if omitted."},"start_date":{"type":"string","format":"date-time","description":"Earliest point in time from which windows are computed."},"end_date":{"type":"string","format":"date-time","nullable":true,"description":"Hard cap — no windows are scheduled after this datetime. `null` means the scheduler runs indefinitely."}}},"DateTimeRangeObject":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Start of the datetime window (ISO 8601)"},"end":{"type":"string","format":"date-time","description":"End of the datetime window (ISO 8601). Must be after `start`."}}}}}}
```

## The BasketOfferSchedulerResponse object

```json
{"openapi":"3.0.3","info":{"title":"Promotions API","version":"1.0.0"},"components":{"schemas":{"BasketOfferSchedulerResponse":{"type":"object","description":"Current state of the scheduler, including read-only computed fields\nthat reflect the currently active window and the next precomputed window.\n","properties":{"cron":{"type":"string","description":"Stored cron expression."},"duration":{"type":"string","nullable":true,"description":"Stored duration as `HH:MM:SS` (e.g. `08:00:00` for 8 hours), or `null` for Mode B schedulers.\n"},"inclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Stored inclusion windows."},"exclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Stored exclusion windows."},"timezone":{"type":"string","description":"Timezone used for cron interpretation."},"start_date":{"type":"string","format":"date-time","nullable":true,"description":"Scheduler start bound."},"end_date":{"type":"string","format":"date-time","nullable":true,"description":"Scheduler end cap, or `null` if indefinite."},"current_period_start_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Start of the currently active window, mirrored to the offer's `start_datetime`. `null` when no window is active."},"current_period_end_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"End of the currently active window, mirrored to the offer's `end_datetime`. `null` when no window is active."},"next_period_start_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Start of the precomputed next window. `null` if no further windows exist within the scheduler's bounds."},"next_period_end_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"End of the precomputed next window."},"next_update_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"When the periodic task will next advance the scheduler to the following window. Equals `current_period_end_date`."}}},"DateTimeRangeObject":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Start of the datetime window (ISO 8601)"},"end":{"type":"string","format":"date-time","description":"End of the datetime window (ISO 8601). Must be after `start`."}}}}}}
```

## The BasketOfferWithSchedulerRequest object

```json
{"openapi":"3.0.3","info":{"title":"Promotions API","version":"1.0.0"},"components":{"schemas":{"BasketOfferWithSchedulerRequest":{"type":"object","description":"Request body for creating a basket offer. The `scheduler` field is optional;\nomit it (or pass `null`) to use manual `start_datetime`/`end_datetime` control.\n`start_datetime` and `end_datetime` **cannot** be set when a `scheduler` object is provided.\n","properties":{"scheduler":{"$ref":"#/components/schemas/BasketOfferSchedulerRequest","nullable":true,"description":"Optional scheduler configuration. Omit or pass `null` for manual date control."}}},"BasketOfferSchedulerRequest":{"type":"object","description":"Configuration for automated scheduling of the offer's active windows.\nAt least one of `cron` (non-empty) or `inclusions` must be provided.\n\n**Mode A** — specific-minute cron: `cron` has a concrete minute value (e.g. `0` or `30`).\n`duration` is **required** and defines how long the offer stays active after each trigger.\n\n**Mode B** — minute-wildcard cron: `cron` minute field is `*` (e.g. `* 9-17 * * 1-5`).\n`duration` must be omitted or `null`; the offer is active for every minute matched by the expression.\n\n**Inclusions-only** — `cron` is an empty string `\"\"` and `inclusions` provides the explicit windows directly.\n","properties":{"cron":{"type":"string","description":"5-field cron expression (`minute hour day-of-month month day-of-week`).\nPass an empty string `\"\"` to use inclusions-only mode.\n"},"duration":{"type":"string","nullable":true,"description":"ISO 8601 duration (e.g. `PT4H`, `PT30M`). **Required** when `cron` uses a specific\nminute value (Mode A). Must be `null` or omitted when the cron minute field is `*`\n(Mode B). Ignored when `cron` is an empty string.\n"},"inclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Explicit datetime windows added on top of any cron-generated windows.\nWindows must not overlap each other.\n"},"exclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Datetime windows subtracted from all candidate windows (cron-generated and included).\nUse to block out holidays or maintenance periods.\n"},"timezone":{"type":"string","description":"IANA timezone name used to interpret the cron fields. Defaults to `UTC` if omitted."},"start_date":{"type":"string","format":"date-time","description":"Earliest point in time from which windows are computed."},"end_date":{"type":"string","format":"date-time","nullable":true,"description":"Hard cap — no windows are scheduled after this datetime. `null` means the scheduler runs indefinitely."}}},"DateTimeRangeObject":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Start of the datetime window (ISO 8601)"},"end":{"type":"string","format":"date-time","description":"End of the datetime window (ISO 8601). Must be after `start`."}}}}}}
```

## The BasketOfferSchedulerPatchRequest object

```json
{"openapi":"3.0.3","info":{"title":"Promotions API","version":"1.0.0"},"components":{"schemas":{"BasketOfferSchedulerPatchRequest":{"type":"object","description":"Request body for a partial update of a basket offer's scheduler.\nPass a `scheduler` object to replace the full scheduler configuration,\n`scheduler: null` to detach it (you may include `start_datetime`/`end_datetime` in the same request),\nor omit `scheduler` entirely to leave it unchanged.\n","properties":{"scheduler":{"$ref":"#/components/schemas/BasketOfferSchedulerRequest","nullable":true,"description":"New scheduler configuration, `null` to detach, or omit to leave unchanged."},"start_datetime":{"type":"string","format":"date-time","nullable":true,"description":"Manual active-from datetime. Only settable when `scheduler` is absent or being set to `null`."},"end_datetime":{"type":"string","format":"date-time","nullable":true,"description":"Manual active-until datetime. Only settable when `scheduler` is absent or being set to `null`."}}},"BasketOfferSchedulerRequest":{"type":"object","description":"Configuration for automated scheduling of the offer's active windows.\nAt least one of `cron` (non-empty) or `inclusions` must be provided.\n\n**Mode A** — specific-minute cron: `cron` has a concrete minute value (e.g. `0` or `30`).\n`duration` is **required** and defines how long the offer stays active after each trigger.\n\n**Mode B** — minute-wildcard cron: `cron` minute field is `*` (e.g. `* 9-17 * * 1-5`).\n`duration` must be omitted or `null`; the offer is active for every minute matched by the expression.\n\n**Inclusions-only** — `cron` is an empty string `\"\"` and `inclusions` provides the explicit windows directly.\n","properties":{"cron":{"type":"string","description":"5-field cron expression (`minute hour day-of-month month day-of-week`).\nPass an empty string `\"\"` to use inclusions-only mode.\n"},"duration":{"type":"string","nullable":true,"description":"ISO 8601 duration (e.g. `PT4H`, `PT30M`). **Required** when `cron` uses a specific\nminute value (Mode A). Must be `null` or omitted when the cron minute field is `*`\n(Mode B). Ignored when `cron` is an empty string.\n"},"inclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Explicit datetime windows added on top of any cron-generated windows.\nWindows must not overlap each other.\n"},"exclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Datetime windows subtracted from all candidate windows (cron-generated and included).\nUse to block out holidays or maintenance periods.\n"},"timezone":{"type":"string","description":"IANA timezone name used to interpret the cron fields. Defaults to `UTC` if omitted."},"start_date":{"type":"string","format":"date-time","description":"Earliest point in time from which windows are computed."},"end_date":{"type":"string","format":"date-time","nullable":true,"description":"Hard cap — no windows are scheduled after this datetime. `null` means the scheduler runs indefinitely."}}},"DateTimeRangeObject":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Start of the datetime window (ISO 8601)"},"end":{"type":"string","format":"date-time","description":"End of the datetime window (ISO 8601). Must be after `start`."}}}}}}
```

## The BasketOfferWithSchedulerResponse object

```json
{"openapi":"3.0.3","info":{"title":"Promotions API","version":"1.0.0"},"components":{"schemas":{"BasketOfferWithSchedulerResponse":{"type":"object","description":"Basket offer response including the optional nested scheduler state.","properties":{"id":{"type":"integer","readOnly":true,"description":"Primary key of the basket offer."},"name":{"type":"string","description":"Display name of the offer."},"status":{"type":"string","description":"Current status of the offer.","enum":["active","passive","used","revoked"]},"start_datetime":{"type":"string","format":"date-time","nullable":true,"description":"When the offer becomes active. Managed by the scheduler when one is attached; otherwise set manually."},"end_datetime":{"type":"string","format":"date-time","nullable":true,"description":"When the offer expires. Managed by the scheduler when one is attached; otherwise set manually."},"scheduler":{"$ref":"#/components/schemas/BasketOfferSchedulerResponse","nullable":true,"description":"Current scheduler state, or `null` if no scheduler is attached."}}},"BasketOfferSchedulerResponse":{"type":"object","description":"Current state of the scheduler, including read-only computed fields\nthat reflect the currently active window and the next precomputed window.\n","properties":{"cron":{"type":"string","description":"Stored cron expression."},"duration":{"type":"string","nullable":true,"description":"Stored duration as `HH:MM:SS` (e.g. `08:00:00` for 8 hours), or `null` for Mode B schedulers.\n"},"inclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Stored inclusion windows."},"exclusions":{"type":"array","items":{"$ref":"#/components/schemas/DateTimeRangeObject"},"description":"Stored exclusion windows."},"timezone":{"type":"string","description":"Timezone used for cron interpretation."},"start_date":{"type":"string","format":"date-time","nullable":true,"description":"Scheduler start bound."},"end_date":{"type":"string","format":"date-time","nullable":true,"description":"Scheduler end cap, or `null` if indefinite."},"current_period_start_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Start of the currently active window, mirrored to the offer's `start_datetime`. `null` when no window is active."},"current_period_end_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"End of the currently active window, mirrored to the offer's `end_datetime`. `null` when no window is active."},"next_period_start_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Start of the precomputed next window. `null` if no further windows exist within the scheduler's bounds."},"next_period_end_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"End of the precomputed next window."},"next_update_date":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"When the periodic task will next advance the scheduler to the following window. Equals `current_period_end_date`."}}},"DateTimeRangeObject":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Start of the datetime window (ISO 8601)"},"end":{"type":"string","format":"date-time","description":"End of the datetime window (ISO 8601). Must be after `start`."}}}}}}
```


---

# 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:

```
GET https://apidocs.akinon.com/commerce-openapis/basket-offers/models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.