Create a basket offer

Creates a basket offer together with its nested promotion, condition, and benefit in a single atomic request.

Offer type rules (validated against user and voucher_code):

sitewide — neither user nor voucher_code may be provided.
voucher_code — voucher_code is required and user must not be provided.
coupon — either user or a bulk_coupon_file is required, and voucher_code must not be provided.
coupon_code — both user and voucher_code are required.

When offer_type is omitted, the server derives it from the presence of user and voucher_code.

Bulk coupons: when a base64-encoded bulk_coupon_file is uploaded (CSV or spreadsheet with an email column header), the offer is stored as bulk_coupon and personal coupons are generated for the matching users asynchronously. The file must contain at least one email belonging to an existing user, and bulk_coupon_file cannot be combined with user.

Date rules: end_datetime must be after start_datetime, and an end_datetime in the past is only accepted for offers created with passive status.

Condition and benefit payloads: the kwargs object of the condition and the benefit must contain the keys required for the chosen condition_type / benefit_type (see the schema descriptions of the Condition and Benefit objects). Amount-based conditions and fixed-amount benefits are rejected when more than one currency is specified in currencies.

Coupon / voucher benefits: a benefit of type coupon or voucher embeds an inner basket offer under kwargs.coupon that is granted after purchase. The inner offer must define exactly one of (start_datetime & end_datetime) or (start_timedelta & end_timedelta), and exactly one of activation_date or activation_timedelta. The inner offer's end date must not precede its activation date or the outer campaign's end date.

Sample product benefits: the benefit and condition must reference different product collections, every product in the benefit collection must have a zero price, and allowed_quantity_per_basket must be 1.

Currencies: when the currencies field is omitted, it defaults to a single-element list containing the shop's default currency, taken from the DEFAULT_CURRENCY dynamic setting (see the Dynamic Settings & Environment Variables section).

Uniqueness: the promotion slug (derived from the promotion name when not sent) and the voucher_code must be unique across all basket offers; violations are reported as business rule errors with the codes promotion_100_1 and promotion_100_2 respectively.

post

/basket_offers/

Authorizations

AuthorizationstringRequired

Token credential sent in the Authorization header, in the form: Token <your-token>. Requires a staff (admin) account.

Body

The payload accepted when creating or updating a basket offer.

labelstring · max: 512 · nullableOptional

Administrative label of the offer. Stored per language; the request language selects the translation being written.

`condition_type`	Required keys in `kwargs`
`quantity`	`price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `distinct_by`, `distinct_by_attribute_key`, `data_sources`
`amount`	`price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `data_sources`
`distinct`	`price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`
`query`	`consume_type`, `query` (must not be empty)

`benefit_type`	Required keys in `kwargs`
`fixed`	`price_type`, `consume_type`, `amount`
`percentage`	`price_type`, `consume_type`, `percentage`
`multibuy`	`price_type`, `consume_type`, `item_count`, `sort_type`, `multibuy_discount_type`, plus `percentage` or `amount` depending on the discount type
`shipping_free`	`price_type`, `consume_type`
`coupon`	`price_type`, `consume_type`, `coupon` (an inner basket offer definition)
`voucher`	`price_type`, `consume_type`, `coupon` (an inner basket offer definition)
`sample_product`	`price_type`, `consume_type`, `allowed_quantity`
`loyalty_point`	`price_type`, `consume_type`, `coupon`, `loyalty_point_coefficient`, `valid_from`, `valid_from_custom_date`, `valid_until`, `valid_until_custom_date`

statusstring · enumRequired

The lifecycle status of a basket offer.

active — eligible for application on the storefront
passive — disabled (expired offers are moved here automatically)
used — single-use offer that has been consumed; cannot be changed again
revoked — withdrawn

Possible values:

offer_typestring · enumOptional

How the offer is matched to a customer. See the Offer Types section under Basket Offers.

Possible values:

voucher_codestring · max: 128 · nullableOptional

Voucher code redeeming the offer. Must be unique across all basket offers.

userinteger · nullableOptional

Identifier of the user the offer is assigned to, for personal offer types.

is_visiblebooleanOptional

Whether the offer is visible on the storefront.

Default: true

is_visible_on_listbooleanOptional

Whether the offer is visible on storefront listing pages.

Default: false

start_datetimestring · nullableOptional

Campaign start. Must precede end_datetime.

end_datetimestring · nullableOptional

Campaign end. A past end date is only accepted together with passive status.

priorityintegerOptional

Application priority; offers with higher priority are evaluated first on the storefront.

Default: 0

is_mergablebooleanOptional

When false, no further offers are applied to a basket after this offer.

Default: true

allowed_quantity_per_basketinteger · min: 1Optional

The maximum number of times the offer may be applied within a single basket.

Default: 1

max_usage_per_userintegerOptional

The maximum number of times a single user may benefit from the offer. 0 means unlimited.

Default: 0

max_stock_limitinteger · nullableOptional

The maximum total number of applications across all baskets. 0 means unlimited.

currenciesstring[] · min: 1Optional

The currencies the offer is valid in. Defaults to the shop's default currency (see the DEFAULT_CURRENCY dynamic setting).

Example: try

is_available_for_data_sourcesbooleanOptional

Whether the offer is exposed to marketplace data sources. When true, both the condition and the benefit must reference a static product collection.

Default: false

kwargsobject · nullableOptional

Free-form extra configuration. When data_source_discount_sharing_rate is present it must be a number between 0 and 100.

start_timedeltainteger · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — validity start, in seconds relative to activation.

end_timedeltainteger · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — validity end, in seconds relative to activation.

activation_timedeltainteger · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — activation delay after purchase, in seconds. Exactly one of activation_timedelta and activation_date must be provided on the inner offer.

activation_datestring · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — absolute activation moment. Exactly one of activation_timedelta and activation_date must be provided on the inner offer.

bulk_coupon_filestringOptional

Base64-encoded CSV or spreadsheet with an email column, listing the users that receive personal coupons. Cannot be combined with user. Turns the offer into a bulk_coupon offer; coupons are generated asynchronously.

bulk_email_filestring · nullableOptional

Base64-encoded file of customer emails imported into the condition as a bulk_email__in rule. Processing is asynchronous; the offer is passive while the file is processed.

bulk_phone_number_filestring · nullableOptional

Base64-encoded file of customer phone numbers imported into the condition as a bulk_phone_number__in rule. Processing is asynchronous; the offer is passive while the file is processed.

Responses

201

The created basket offer.

application/json

A basket offer as returned by the API.

labelstring · max: 512 · nullableOptional

Administrative label of the offer. Stored per language; the request language selects the translation being written.

`condition_type`	Required keys in `kwargs`
`quantity`	`price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `distinct_by`, `distinct_by_attribute_key`, `data_sources`
`amount`	`price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`, `data_sources`
`distinct`	`price_type`, `consume_type`, `value`, and optionally `sub_conditions`, `excluded_sub_conditions`, `query`, `overlimit`
`query`	`consume_type`, `query` (must not be empty)

`benefit_type`	Required keys in `kwargs`
`fixed`	`price_type`, `consume_type`, `amount`
`percentage`	`price_type`, `consume_type`, `percentage`
`multibuy`	`price_type`, `consume_type`, `item_count`, `sort_type`, `multibuy_discount_type`, plus `percentage` or `amount` depending on the discount type
`shipping_free`	`price_type`, `consume_type`
`coupon`	`price_type`, `consume_type`, `coupon` (an inner basket offer definition)
`voucher`	`price_type`, `consume_type`, `coupon` (an inner basket offer definition)
`sample_product`	`price_type`, `consume_type`, `allowed_quantity`
`loyalty_point`	`price_type`, `consume_type`, `coupon`, `loyalty_point_coefficient`, `valid_from`, `valid_from_custom_date`, `valid_until`, `valid_until_custom_date`

statusstring · enumRequired

The lifecycle status of a basket offer.

active — eligible for application on the storefront
passive — disabled (expired offers are moved here automatically)
used — single-use offer that has been consumed; cannot be changed again
revoked — withdrawn

Possible values:

offer_typestring · enumOptional

How the offer is matched to a customer. See the Offer Types section under Basket Offers.

Possible values:

voucher_codestring · max: 128 · nullableOptional

Voucher code redeeming the offer. Must be unique across all basket offers.

userobject · nullableOptional

When the offer is assigned to a user, the user is returned expanded as an object (identifier, email, name fields) rather than as a bare identifier.

is_visiblebooleanOptional

Whether the offer is visible on the storefront.

Default: true

is_visible_on_listbooleanOptional

Whether the offer is visible on storefront listing pages.

Default: false

start_datetimestring · nullableOptional

Campaign start. Must precede end_datetime.

end_datetimestring · nullableOptional

Campaign end. A past end date is only accepted together with passive status.

priorityintegerOptional

Application priority; offers with higher priority are evaluated first on the storefront.

Default: 0

is_mergablebooleanOptional

When false, no further offers are applied to a basket after this offer.

Default: true

allowed_quantity_per_basketinteger · min: 1Optional

The maximum number of times the offer may be applied within a single basket.

Default: 1

max_usage_per_userintegerOptional

The maximum number of times a single user may benefit from the offer. 0 means unlimited.

Default: 0

max_stock_limitinteger · nullableOptional

The maximum total number of applications across all baskets. 0 means unlimited.

currenciesstring[] · min: 1Optional

The currencies the offer is valid in. Defaults to the shop's default currency (see the DEFAULT_CURRENCY dynamic setting).

Example: try

is_available_for_data_sourcesbooleanOptional

Whether the offer is exposed to marketplace data sources. When true, both the condition and the benefit must reference a static product collection.

Default: false

kwargsobject · nullableOptional

Free-form extra configuration. When data_source_discount_sharing_rate is present it must be a number between 0 and 100.

start_timedeltainteger · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — validity start, in seconds relative to activation.

end_timedeltainteger · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — validity end, in seconds relative to activation.

activation_timedeltainteger · nullableOptional

activation_datestring · nullableOptional

Only for inner offers embedded in coupon / voucher benefits — absolute activation moment. Exactly one of activation_timedelta and activation_date must be provided on the inner offer.

bulk_coupon_filestringOptional

bulk_email_filestring · nullableOptional

Base64-encoded file of customer emails imported into the condition as a bulk_email__in rule. Processing is asynchronous; the offer is passive while the file is processed.

bulk_phone_number_filestring · nullableOptional

Base64-encoded file of customer phone numbers imported into the condition as a bulk_phone_number__in rule. Processing is asynchronous; the offer is passive while the file is processed.

pkintegerOptional

Unique basket offer identifier.

modified_datestring · date-timeOptional

The moment the offer was last modified.

remaining_stock_limitintegerOptional

Only present when max_stock_limit is positive — the number of applications still available.

400

The request contains invalid or missing data, or violates a business rule — for example a promotion slug that already exists (promotion_100_1) or a voucher code that already exists (promotion_100_2).

application/json

401

Authentication credentials were not provided or are invalid.

application/json

403

The authenticated user does not have administrator privileges.

application/json

post/basket_offers/

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

{
  "label": null,
  "promotion": {
    "name": "text",
    "slug": "text"
  },
  "condition": {
    "condition_type": "distinct",
    "product_collection": null,
    "upsell_message": "text",
    "kwargs": {}
  },
  "benefit": {
    "benefit_type": "multibuy",
    "product_collection": null,
    "kwargs": {}
  },
  "status": "active",
  "offer_type": "sitewide",
  "voucher_code": null,
  "user": null,
  "is_visible": true,
  "is_visible_on_list": false,
  "start_datetime": null,
  "end_datetime": null,
  "priority": 0,
  "is_mergable": true,
  "allowed_quantity_per_basket": 1,
  "max_usage_per_user": 0,
  "max_stock_limit": null,
  "currencies": [
    "try"
  ],
  "is_available_for_data_sources": false,
  "kwargs": null,
  "start_timedelta": null,
  "end_timedelta": null,
  "activation_timedelta": null,
  "activation_date": null,
  "bulk_coupon_file": "text",
  "bulk_email_file": null,
  "bulk_phone_number_file": null
}

{
  "label": null,
  "promotion": {
    "pk": 1,
    "name": "text",
    "slug": "text"
  },
  "condition": {
    "pk": 1,
    "condition_type": "distinct",
    "product_collection": null,
    "upsell_message": "text",
    "kwargs": {}
  },
  "benefit": {
    "pk": 1,
    "benefit_type": "multibuy",
    "product_collection": null,
    "kwargs": {}
  },
  "status": "active",
  "offer_type": "sitewide",
  "voucher_code": null,
  "user": null,
  "is_visible": true,
  "is_visible_on_list": false,
  "start_datetime": null,
  "end_datetime": null,
  "priority": 0,
  "is_mergable": true,
  "allowed_quantity_per_basket": 1,
  "max_usage_per_user": 0,
  "max_stock_limit": null,
  "currencies": [
    "try"
  ],
  "is_available_for_data_sources": false,
  "kwargs": null,
  "start_timedelta": null,
  "end_timedelta": null,
  "activation_timedelta": null,
  "activation_date": null,
  "bulk_coupon_file": "text",
  "bulk_email_file": null,
  "bulk_phone_number_file": null,
  "pk": 1,
  "modified_date": "2026-01-01T00:00:00.000Z",
  "remaining_stock_limit": 1
}

PreviousList basket offers NextRetrieve a basket offer

Last updated 15 days ago

Was this helpful?