Retrieve a basket offer

Returns a single basket offer with its nested promotion, condition, and benefit.

When the offer defines a positive max_stock_limit, the response additionally reports remaining_stock_limit — the number of applications still available.

get

/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.

Responses

200

The requested 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.

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

get/basket_offers/{id}/

GET /api/remote/1/basket_offers/{id}/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "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
}