Partially update a basket offer

Partially updates a basket offer. Only the provided fields are changed; the validation rules described under Update a basket offer apply to the fields that are sent.

patch

/basket_offers/{id}/

Authorizations

AuthorizationstringRequired

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

Path parameters

idintegerRequired

The unique identifier of the basket offer.

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

200

The updated 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

404

The requested basket offer does not exist.

application/json

patch/basket_offers/{id}/

PATCH /api/remote/1/basket_offers/{id}/ 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
}

PreviousUpdate a basket offer NextSet the status of a basket offer

Last updated 15 days ago

Was this helpful?