Promotions & Extras

Checkout Promotions & Extras

Apply discounts and promotional offers that reduce the order total or add complimentary items.

Coupons apply a single-use discount code to the basket.

Vouchers apply a voucher code that may provide a fixed or percentage discount.

Campaigns present available promotional campaigns the customer can activate.

Sample Products let customers add a complimentary product sample to their order.

Authentication

These endpoints support both authenticated and anonymous sessions.

• Authenticated users: Session cookie (sessionid) tracks checkout progress.

• Anonymous users: Guest checkout is available when the CAN_GUEST_PURCHASE setting is enabled.

Request Format

Include the following header in all checkout requests:

• x-requested-with: XMLHttpRequest

Get Coupon Selection Page context

get

Returns the available coupons for the current user. This page runs as an independent step, meaning it does not reset or block other checkout steps and can be submitted at any point once the precondition is satisfied.

Coupon Types:

• Coupon (offer_type = coupon): Standard single-use coupon assigned to the user

• Bulk Coupon (offer_type = bulk_coupon): A coupon from a bulk voucher batch, assigned to the user's BulkVoucherCode with an ACTIVE status

Applied Coupons:

• Offer applications are evaluated live via OfferApplicator on each GET request

• Coupons currently applied to the basket have is_applied: true

Preconditions:

• No strict preconditions — available to both authenticated and anonymous users

• Anonymous users see an empty coupon list (coupons are user-specific)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Coupon selection page context retrieved

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

get/orders/checkout/?page=CouponSelectionPage

HTTPcURLJavaScriptPython

GET /orders/checkout/?page=CouponSelectionPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Accept: */*

200

Coupon selection page context retrieved

{
  "context_list": [
    {
      "page_name": "CouponSelectionPage",
      "page_slug": "couponselectionpage",
      "page_context": {
        "available_coupons": [
          {
            "pk": 101,
            "label": "SUMMER20",
            "is_applied": true,
            "start_datetime": "2024-06-01T00:00:00Z",
            "end_datetime": "2024-08-31T23:59:59Z"
          },
          {
            "pk": 102,
            "label": "NEWUSER10",
            "is_applied": false,
            "start_datetime": "2024-01-01T00:00:00Z",
            "end_datetime": "2024-12-31T23:59:59Z"
          }
        ]
      }
    }
  ],
  "errors": [],
  "template_name": "orders/checkout.html"
}

Add or Remove a Coupon

post

Adds or removes a coupon from the current checkout session. This is an independent step and does not determine the next checkout page. The checkout flow proceeds based on the current checkout state.

Required Fields:

• coupon: The primary key of the BasketOffer record as a string

• action: Either "add" to apply the coupon or "remove" to unapply it

State Changes:

• The coupon PK is added to or removed from pre_order.data["coupons"]

• Offer applications are recalculated on the next GET request

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

couponstringRequired

Primary key of the BasketOffer record to add or remove, as a string.

Example: 101

actionstring · enumRequired

Action to perform: "add" to apply the coupon or "remove" to unapply it.

Example: addPossible values:

Responses

200

Coupon action processed

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

post/orders/checkout/?page=CouponSelectionPage

HTTPcURLJavaScriptPython

POST /orders/checkout/?page=CouponSelectionPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 31

"coupon='101'&action='add'"

Add a coupon to the checkoutRemove a coupon from the checkout

200

Coupon action processed

{
  "context_list": [],
  "errors": {}
}

Get Voucher Code Page context

get

Returns the current voucher code set on the checkout session, if any. This page runs as an independent step, meaning it does not reset or block other checkout steps and can be submitted at any point once the precondition is satisfied.

Voucher vs Coupon:

• CouponSelectionPage manages user-specific BasketOffer coupons

• VoucherCodePage manages a free-text voucher code stored on pre_order.voucher_code

• The voucher code is applied to the basket at order creation time via OfferApplicator

Validation:

• The submitted voucher code is validated by running the offer applicator in a dry-run mode (without modifying the basket)

• If the code is not recognized or has already been used, a validation error is returned

Page Context:

• voucher_code: The voucher code currently set, or null if none

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Voucher code page context retrieved

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

get/orders/checkout/?page=VoucherCodePage

HTTPcURLJavaScriptPython

GET /orders/checkout/?page=VoucherCodePage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Accept: */*

200

Voucher code page context retrieved

{
  "context_list": [
    {
      "page_name": "VoucherCodePage",
      "page_slug": "vouchercodepage",
      "page_context": {
        "voucher_code": null
      }
    }
  ],
  "errors": [],
  "template_name": "orders/checkout.html"
}

Apply or Clear Voucher Code

post

Sets or clears the voucher code on the checkout session. This is an independent step and does not determine the next checkout page. The checkout flow proceeds based on the current checkout state.

Required Fields:

• voucher_code: The voucher code string to apply (optional, max 128 characters). Whitespace is trimmed automatically. Submit an empty value or omit the field to clear the voucher code.

Validation:

• If a non-empty voucher code is provided, it is validated using OfferApplicator in a dry-run mode (on a copy of the pre-order and basket)

• The code is considered valid only if it results in an applied and non-failed voucher

• An invalid code returns a validation error in the errors field

State Changes:

• pre_order.voucher_code is set to the validated code

• Submitting an empty value clears pre_order.voucher_code (sets it to null)

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

voucher_codestring · max: 128Optional

Voucher code to apply to the checkout session. Leading and trailing whitespace is trimmed automatically. Submit an empty string or omit this field to clear the currently set voucher code. Maximum 128 characters.

Example: WELCOME2024

Responses

200

Voucher code processed

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

post/orders/checkout/?page=VoucherCodePage

HTTPcURLJavaScriptPython

POST /orders/checkout/?page=VoucherCodePage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 30

"voucher_code='WELCOME2024'"

Apply a voucher codeClear the current voucher code

200

Voucher code processed

{
  "context_list": [],
  "errors": {}
}

Get Campaign List Page context

get

Returns the context for the Campaign List Page, which queries the payment gateway for available campaigns associated with the selected credit card. This page is only reachable when a credit card payment option is selected, card details are present in the pre-order, and the active payment gateway supports campaign querying.

Preconditions:

• Basket must not be empty

• A credit card payment option must be selected

• Card information must be present in the current pre-order

• The active payment gateway must support campaign listing

Skip Conditions:

• Page is skipped if campaign data has already been fetched (i.e., campaigns is not null in the current pre-order state)

available_for_post_order: true

Next Pages (determined dynamically):

• CampaignSelectionPage — always, after campaign data is fetched

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Campaign List Page context retrieved

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

get/orders/checkout/?page=CampaignListPage

HTTPcURLJavaScriptPython

GET /orders/checkout/?page=CampaignListPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Accept: */*

200

Campaign List Page context retrieved

{
  "context_list": [
    {
      "page_name": "CampaignListPage",
      "page_slug": "campaignlistpage",
      "page_context": {}
    }
  ],
  "pre_order": {
    "user_email": "[e-mail]",
    "payment_option": {
      "pk": 3,
      "name": "Credit Card",
      "slug": "credit-card",
      "payment_type": "credit_card",
      "payment_type_label": "Credit Card"
    },
    "campaigns": null
  },
  "errors": [],
  "template_name": "orders/checkout.html"
}

Query available campaigns for the selected credit card

post

Submits the full card number to the payment gateway and retrieves the list of available campaigns. The returned campaign list is stored in the pre-order state and used by the subsequent CampaignSelectionPage to allow the user to choose a campaign.

Required Fields:

• card_number: The full credit card number. Spaces are stripped before validation. Must pass card number format validation.

Validation:

• card_number must be a valid card number; all spaces are removed before the check is applied

• If the card number is invalid, an error is returned and the user remains on CampaignListPage

State Update:

• On success, campaigns in the pre-order is populated with the list of campaign objects returned by the payment gateway. If the gateway returns no campaigns, campaigns is set to [] (empty array).

Backward Navigation:

• When navigating backward from this page, campaigns is reset to null, requiring the user to re-submit the card number.

Next Pages:

• CampaignSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

card_numberstringRequired

The full credit card number. Leading, trailing, and internal spaces are stripped before validation is applied. Must be a valid card number.

Example: 5400010000000004

Responses

200

Campaign list retrieved successfully

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

post/orders/checkout/?page=CampaignListPage

HTTPcURLJavaScriptPython

POST /orders/checkout/?page=CampaignListPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 34

"card_number='5400010000000004'"

200

Campaign list retrieved successfully

{
  "context_list": [
    {
      "page_name": "CampaignSelectionPage",
      "page_slug": "campaignselectionpage",
      "page_context": {
        "campaigns": [
          {
            "code": "CAMP001",
            "name": "3 Installments Campaign"
          },
          {
            "code": "CAMP002",
            "name": "6 Installments Campaign"
          }
        ]
      }
    }
  ],
  "pre_order": {
    "user_email": "[e-mail]",
    "payment_option": {
      "pk": 3,
      "name": "Credit Card",
      "slug": "credit-card",
      "payment_type": "credit_card",
      "payment_type_label": "Credit Card"
    },
    "campaigns": [
      {
        "code": "CAMP001",
        "name": "3 Installments Campaign"
      },
      {
        "code": "CAMP002",
        "name": "6 Installments Campaign"
      }
    ]
  },
  "errors": {},
  "template_name": "orders/checkout.html"
}

Get Campaign Selection Page context

get

Returns the context for the Campaign Selection Page, which presents the list of campaigns fetched from the payment gateway in the preceding CampaignListPage step. The user selects one campaign from this list to apply to the order.

Preconditions:

• Campaign data must have been fetched (i.e., campaigns must not be null in the current pre-order state; an empty list [] is accepted)

Skip Conditions:

• Page is skipped if a campaign has already been selected (i.e., selected_campaign is not null in the current pre-order state)

available_for_post_order: true

Next Pages (determined dynamically):

• Proceeds to the next applicable checkout step once a campaign is selected

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Campaign Selection Page context retrieved

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

get/orders/checkout/?page=CampaignSelectionPage

HTTPcURLJavaScriptPython

GET /orders/checkout/?page=CampaignSelectionPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Accept: */*

200

Campaign Selection Page context retrieved

{
  "context_list": [
    {
      "page_name": "CampaignSelectionPage",
      "page_slug": "campaignselectionpage",
      "page_context": {
        "campaigns": [
          {
            "code": "CAMP001",
            "name": "3 Installments Campaign"
          },
          {
            "code": "CAMP002",
            "name": "6 Installments Campaign"
          }
        ]
      }
    }
  ],
  "pre_order": {
    "user_email": "[e-mail]",
    "payment_option": {
      "pk": 3,
      "name": "Credit Card",
      "slug": "credit-card",
      "payment_type": "credit_card",
      "payment_type_label": "Credit Card"
    },
    "campaigns": [
      {
        "code": "CAMP001",
        "name": "3 Installments Campaign"
      },
      {
        "code": "CAMP002",
        "name": "6 Installments Campaign"
      }
    ],
    "selected_campaign": null
  },
  "errors": [],
  "template_name": "orders/checkout.html"
}

Select a campaign to apply to the order

post

Submits the user's chosen campaign code. The submitted code is validated against the list of campaigns previously fetched from the payment gateway. On success, the selected campaign is stored in the pre-order state.

Required Fields:

• campaign: The code of the campaign to apply. Must be one of the codes present in the campaigns list of the current pre-order state.

Validation:

• campaign must match a code from the available campaigns list. If the submitted code is not found in the list, a validation error is returned and the user remains on CampaignSelectionPage.

State Update:

• On success, selected_campaign in the pre-order is set to the submitted campaign code.

Backward Navigation:

• When navigating backward from this page, selected_campaign is reset to null, requiring the user to re-select a campaign.

Next Pages:

• The checkout flow advances to the next applicable step as determined by the overall checkout state.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

campaignstringRequired

The code of the campaign to apply to the order. Must match one of the campaign codes present in the campaigns list of the current pre-order state. Submitting a code not present in that list causes a validation error.

Example: CAMP001

Responses

200

Campaign selected successfully

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

post/orders/checkout/?page=CampaignSelectionPage

HTTPcURLJavaScriptPython

POST /orders/checkout/?page=CampaignSelectionPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 22

"campaign='CAMP001'"

200

Campaign selected successfully

{
  "context_list": [
    {
      "page_name": "CampaignSelectionPage",
      "page_slug": "campaignselectionpage",
      "page_context": {
        "campaigns": [
          {
            "code": "CAMP001",
            "name": "3 Installments Campaign"
          },
          {
            "code": "CAMP002",
            "name": "6 Installments Campaign"
          }
        ]
      }
    }
  ],
  "pre_order": {
    "user_email": "[e-mail]",
    "payment_option": {
      "pk": 3,
      "name": "Credit Card",
      "slug": "credit-card",
      "payment_type": "credit_card",
      "payment_type_label": "Credit Card"
    },
    "campaigns": [
      {
        "code": "CAMP001",
        "name": "3 Installments Campaign"
      },
      {
        "code": "CAMP002",
        "name": "6 Installments Campaign"
      }
    ],
    "selected_campaign": "CAMP001"
  },
  "errors": {},
  "template_name": "orders/checkout.html"
}

Get Sample Product Page context

get

Returns the list of sample products available for selection, based on the offer/discount applications on the current basket. This page is shown when active campaigns include sample product discounts.

Preconditions:

• Basket must not be empty

• A shipping option must already be selected (check_shipping_option_selected)

Skip Conditions:

• Page is skipped if sample products have already been selected or declined (i.e., sample_products or unwanted_sample_products is set in pre_order.data)

Previous Page: ShippingOptionSelectionPage (or configured variant)

Next Page: PaymentOptionSelectionPage

Note: This page appears only when at least one active offer discount includes sample_product_discounts. If no such discounts are applied to the basket, this page will not appear in the flow.

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses

200

Sample Product Page context retrieved

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

get/orders/checkout/?page=SampleProductPage

HTTPcURLJavaScriptPython

GET /orders/checkout/?page=SampleProductPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Accept: */*

200

Sample Product Page context retrieved

{
  "context_list": [
    {
      "page_name": "SampleProductPage",
      "page_slug": "sampleproductpage",
      "page_context": {
        "sample_products": [
          {
            "pk": 101,
            "name": "Sample Moisturizer",
            "sku": "SAMPLE-MOIST-001",
            "base_code": "SAMPLE-MOIST",
            "absolute_url": "/products/sample-moisturizer/",
            "price": "0.00",
            "retail_price": "0.00",
            "currency_type": "try",
            "price_type": "default",
            "unit_type": "quantity",
            "tax_rate": "18.00",
            "in_stock": true,
            "stock": 10,
            "is_ready_to_basket": true,
            "product_type": "simple_product",
            "attributes": {},
            "attributes_kwargs": {},
            "extra_attributes": {},
            "productimage_set": [],
            "productvideo_set": [],
            "form_schema": [],
            "data_source": null,
            "category": null
          }
        ],
        "allowed_quantity": 1
      }
    }
  ],
  "pre_order": {
    "user_email": "[e-mail]",
    "shipping_option": {
      "pk": 1,
      "name": "Standard Shipping",
      "slug": "standard-shipping"
    }
  },
  "errors": [],
  "template_name": "orders/checkout.html"
}

Select or decline sample products

post

Accepts the user's sample product selection. The user can either select one or more products (up to allowed_quantity) or submit an empty list to explicitly decline all sample products.

Fields:

• sample_products: List of product PKs to add as samples. Must be from the available sample product IDs for the current basket discounts. Duplicates are deduplicated automatically. Can be an empty list to decline all samples.

Validation:

• The number of selected products must not exceed allowed_quantity. If it does, a validation error is returned.

• Each submitted PK must belong to the set of available sample products for the current offer discount applications.

State Update:

• If products are selected: pre_order.data['sample_products'] is set to the selected product list.

• If the list is empty (decline): pre_order.data['unwanted_sample_products'] is set to true and sample_products is removed.

Backward Navigation:

• When navigating backward, both sample_products and unwanted_sample_products are removed from pre_order.data.

Next Pages:

• PaymentOptionSelectionPage

Header parameters

x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:

CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

application/x-www-form-urlencoded

sample_productsinteger[]Required

List of product PKs to add as sample products. Must be from the set of available sample products for the current basket's offer discount applications. Duplicates are deduplicated automatically. Submit an empty array to explicitly decline all sample products (sets unwanted_sample_products = true). The count must not exceed the allowed_quantity returned in the page context.

Example: [101]

Responses

200

Sample product selection applied or validation error

application/json

errorsone of · nullableOptional

or

string[]Optional

template_namestringOptional

post/orders/checkout/?page=SampleProductPage

HTTPcURLJavaScriptPython

POST /orders/checkout/?page=SampleProductPage HTTP/1.1
Host: sandbox.akinon.com
x-requested-with: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 25

"sample_products=[101]"

User selects one sample productUser declines all sample products

200

Sample product selection applied or validation error

{
  "context_list": [
    {
      "page_name": "PaymentOptionSelectionPage",
      "page_slug": "paymentoptionselectionpage",
      "page_context": {
        "payment_options": [],
        "unavailable_options": []
      }
    }
  ],
  "pre_order": {
    "user_email": "[e-mail]"
  },
  "errors": {},
  "template_name": "orders/checkout.html"
}