Basket Offers

Create a basket offer (with optional scheduler)

post

/basket_offers/

Creates a new basket offer. An optional scheduler object can be included to delegate start_datetime/end_datetime management to the scheduler engine.

Scheduler modes

Mode	cron value	duration
A — fixed-window	5-field expression with a specific minute (e.g. 30 9 * * 1)	Required — ISO 8601 duration (e.g. PT4H). The offer is active from the cron trigger time until the duration elapses.
B — minute-range	5-field expression with * in the minute field (e.g. * 9-17 * * 1-5)	Must be omitted or null. The offer is active for every minute matched by the expression.
Inclusions-only	Empty string ""	Omit or null. The inclusions list alone drives the windows.

You must provide at least one of cron (non-empty) or inclusions.

Constraints

• inclusions windows must not overlap each other.

• The scheduler cannot be attached to an offer whose status is used or revoked.

• While a scheduler is active, start_datetime and end_datetime cannot be set manually — the scheduler owns them.

• Returns 400 if the apply_scheduler_windows periodic task is not registered in the Celery beat schedule.

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Header parameters

Accept-LanguagestringOptionalExample: tr

Body

Request body for creating a basket offer. The scheduler field is optional; omit it (or pass null) to use manual start_datetime/end_datetime control. start_datetime and end_datetime cannot be set when a scheduler object is provided.

Responses

201

Basket offer created successfully

application/json

Basket offer response including the optional nested scheduler state.

idintegerRead-onlyOptional

Primary key of the basket offer.

Example: 42

namestringOptional

Display name of the offer.

Example: Monday flash sale

statusstring · enumOptional

Current status of the offer.

Example: activePossible values:

start_datetimestring · date-time · nullableOptional

When the offer becomes active. Managed by the scheduler when one is attached; otherwise set manually.

Example: 2026-05-05T09:00:00Z

end_datetimestring · date-time · nullableOptional

When the offer expires. Managed by the scheduler when one is attached; otherwise set manually.

Example: 2026-05-05T17:00:00Z

400

Validation error

application/json

post/basket_offers/

POST /api/v1/remote/1/basket_offers/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 184

{
  "name": "Monday flash sale",
  "offer_type": "sitewide",
  "scheduler": {
    "cron": "0 9 * * 1",
    "duration": "PT8H",
    "timezone": "Europe/Istanbul",
    "start_date": "2026-05-01T00:00:00Z",
    "end_date": null
  }
}

{
  "id": 42,
  "name": "Monday flash sale",
  "status": "active",
  "start_datetime": "2026-05-05T09:00:00Z",
  "end_datetime": "2026-05-05T17:00:00Z",
  "scheduler": {
    "cron": "0 9 * * 1",
    "duration": "08:00:00",
    "inclusions": [],
    "exclusions": [],
    "timezone": "Europe/Istanbul",
    "start_date": "2026-05-01T00:00:00Z",
    "end_date": null,
    "current_period_start_date": "2026-05-05T09:00:00Z",
    "current_period_end_date": "2026-05-05T17:00:00Z",
    "next_period_start_date": "2026-05-12T09:00:00Z",
    "next_period_end_date": "2026-05-12T17:00:00Z",
    "next_update_date": "2026-05-05T17:00:00Z"
  }
}

Full update of a basket offer's scheduler

put

/basket_offers/{id}/

Fully replaces a basket offer. All writable fields must be provided. Scheduler behaviour is identical to PATCH — pass a scheduler object to replace the scheduler configuration, scheduler: null to detach it, or omit scheduler to leave it unchanged.

Constraints

• Mode A requires duration; Mode B forbids it.

• inclusions must not overlap.

• start_datetime/end_datetime cannot be changed while a scheduler remains attached (unless scheduler: null is also in the payload).

• Cannot attach a scheduler to an offer with status used or revoked.

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

Primary key of the basket offer to update

Header parameters

Accept-LanguagestringOptionalExample: tr

Body

Request body for a partial update of a basket offer's scheduler. Pass a scheduler object to replace the full scheduler configuration, scheduler: null to detach it (you may include start_datetime/end_datetime in the same request), or omit scheduler entirely to leave it unchanged.

start_datetimestring · date-time · nullableOptional

Manual active-from datetime. Only settable when scheduler is absent or being set to null.

Example: 2026-07-01T08:00:00Z

end_datetimestring · date-time · nullableOptional

Manual active-until datetime. Only settable when scheduler is absent or being set to null.

Example: 2026-07-01T20:00:00Z

Responses

200

Basket offer updated successfully

application/json

Basket offer response including the optional nested scheduler state.

idintegerRead-onlyOptional

Primary key of the basket offer.

Example: 42

namestringOptional

Display name of the offer.

Example: Monday flash sale

statusstring · enumOptional

Current status of the offer.

Example: activePossible values:

start_datetimestring · date-time · nullableOptional

When the offer becomes active. Managed by the scheduler when one is attached; otherwise set manually.

Example: 2026-05-05T09:00:00Z

end_datetimestring · date-time · nullableOptional

When the offer expires. Managed by the scheduler when one is attached; otherwise set manually.

Example: 2026-05-05T17:00:00Z

400

Validation error

application/json

404

Basket offer not found

put/basket_offers/{id}/

PUT /api/v1/remote/1/basket_offers/{id}/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "scheduler": {
    "cron": "0 10 * * 2",
    "duration": "PT6H",
    "timezone": "Europe/Istanbul",
    "start_date": "2026-06-01T00:00:00Z"
  }
}

{
  "id": 42,
  "name": "Monday flash sale",
  "status": "active",
  "start_datetime": "2026-05-05T09:00:00Z",
  "end_datetime": "2026-05-05T17:00:00Z",
  "scheduler": {
    "cron": "0 9 * * 1",
    "duration": "08:00:00",
    "inclusions": [
      {
        "start": "2026-06-01T10:00:00Z",
        "end": "2026-06-01T14:00:00Z"
      }
    ],
    "exclusions": [
      {
        "start": "2026-06-01T10:00:00Z",
        "end": "2026-06-01T14:00:00Z"
      }
    ],
    "timezone": "Europe/Istanbul",
    "start_date": "2026-05-01T00:00:00Z",
    "end_date": null,
    "current_period_start_date": "2026-05-05T09:00:00Z",
    "current_period_end_date": "2026-05-05T17:00:00Z",
    "next_period_start_date": "2026-05-12T09:00:00Z",
    "next_period_end_date": "2026-05-12T17:00:00Z",
    "next_update_date": "2026-05-05T17:00:00Z"
  }
}

Update a basket offer's scheduler

patch

/basket_offers/{id}/

Partially updates a basket offer. Use this endpoint to:

• Modify scheduler fields — send a scheduler object with the fields to update. All scheduler fields are replaced atomically; the full scheduler config must be valid after the update.

• Detach the scheduler — send scheduler: null. After detachment the offer reverts to manual start_datetime/end_datetime control. You may set those fields in the same request.

Constraints

• Mode A requires duration; Mode B forbids it.

• inclusions must not overlap.

• start_datetime/end_datetime cannot be changed while a scheduler remains attached (unless scheduler: null is also in the payload).

• Cannot attach a scheduler to an offer with status used or revoked.

Authorizations

AuthorizationstringRequired

Token-based authentication with required prefix "Token"

Path parameters

idintegerRequired

Primary key of the basket offer to update

Header parameters

Accept-LanguagestringOptionalExample: tr

Body

Request body for a partial update of a basket offer's scheduler. Pass a scheduler object to replace the full scheduler configuration, scheduler: null to detach it (you may include start_datetime/end_datetime in the same request), or omit scheduler entirely to leave it unchanged.

start_datetimestring · date-time · nullableOptional

Manual active-from datetime. Only settable when scheduler is absent or being set to null.

Example: 2026-07-01T08:00:00Z

end_datetimestring · date-time · nullableOptional

Manual active-until datetime. Only settable when scheduler is absent or being set to null.

Example: 2026-07-01T20:00:00Z

Responses

200

Basket offer updated successfully

application/json

Basket offer response including the optional nested scheduler state.

idintegerRead-onlyOptional

Primary key of the basket offer.

Example: 42

namestringOptional

Display name of the offer.

Example: Monday flash sale

statusstring · enumOptional

Current status of the offer.

Example: activePossible values:

start_datetimestring · date-time · nullableOptional

When the offer becomes active. Managed by the scheduler when one is attached; otherwise set manually.

Example: 2026-05-05T09:00:00Z

end_datetimestring · date-time · nullableOptional

When the offer expires. Managed by the scheduler when one is attached; otherwise set manually.

Example: 2026-05-05T17:00:00Z

400

Validation error

application/json

404

Basket offer not found

patch/basket_offers/{id}/

PATCH /api/v1/remote/1/basket_offers/{id}/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "scheduler": {
    "cron": "0 9 * * 1",
    "duration": "PT8H",
    "timezone": "America/New_York"
  }
}

{
  "id": 42,
  "name": "Monday flash sale",
  "status": "active",
  "start_datetime": "2026-05-05T09:00:00Z",
  "end_datetime": "2026-05-05T17:00:00Z",
  "scheduler": {
    "cron": "0 9 * * 1",
    "duration": "08:00:00",
    "inclusions": [],
    "exclusions": [],
    "timezone": "America/New_York",
    "current_period_start_date": "2026-05-05T09:00:00Z",
    "current_period_end_date": "2026-05-05T17:00:00Z",
    "next_period_start_date": "2026-05-12T09:00:00Z",
    "next_period_end_date": "2026-05-12T17:00:00Z",
    "next_update_date": "2026-05-05T17:00:00Z"
  }
}