For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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

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.

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.

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
}

Last updated

Was this helpful?