Aksal Black Partner APIs

These endpoints allow Aksal to retrieve Aksal Black customer information: discount tier, active program challenges, and purchase history.

Authentication

• Uses signature authentication

Header	Description
X-SIGNATURE	The signature header of the request

See 2-security.md for signature generation details.

Base path

/api/v1/partner/aksal/

Customer identifier

All endpoints below use the same path parameter, identifier, to look up an enrolled Aksal Black customer. It accepts either:

Value type	Description	Example
Aksal Black card number	The customer's Aksal Black card number	AKSAL-BLACK-0001
Mobile phone number	The customer's mobile number on file	0611223344, +212611223344, or 212611223344

Spaces in the value are ignored. For phone numbers, local Moroccan formats starting with 0 are normalized to the international +212 format before lookup.

Endpoints

1) Black card tier

Retrieve the discount tier and customer summary for an Aksal Black customer.

GET /api/v1/partner/aksal/black-card/<identifier>/tier

Parameter	Type	Description
identifier	string	The Aksal Black card number or the customer's mobile phone number (see above)

Sample request (card number)

GET https://app.kenzup.com/api/v1/partner/aksal/black-card/AKSAL-BLACK-0001/tier

Sample request (mobile phone number)

GET https://app.kenzup.com/api/v1/partner/aksal/black-card/0611223344/tier

Status Code: 200

{
  "first_name": "Ahmed",
  "last_name": "Benali",
  "customer_phone_number": "+212611223344",
  "balance": "250.50",
  "discount_pct": "15.00",
  "label_fr": "Tier Or",
  "label_ar": "الدرجة الذهبية",
  "label_en": "Gold Tier",
  "description_fr": "Bénéficiez de 15% de réduction sur tous vos achats Aksal.",
  "description_ar": "استمتع بخصم 15% على جميع مشترياتك في أكسال.",
  "description_en": "Enjoy 15% off on all your Aksal purchases.",
  "remaining_for_next_tier": "3000.00",
  "next_tier_labels": {
    "label_fr": "Tier Platine",
    "label_ar": "الدرجة البلاتينية",
    "label_en": "Platinum Tier"
  }
}

Field	Type	Description
first_name	string	Customer first name
last_name	string	Customer last name
customer_phone_number	string	Customer mobile number in international format
balance	decimal	Customer points wallet balance
discount_pct	decimal	Discount percentage for this tier. Can be null if not yet configured.
label_fr	string	Tier name in French
label_ar	string	Tier name in Arabic
label_en	string	Tier name in English
description_fr	string	Tier description in French. Can be null.
description_ar	string	Tier description in Arabic. Can be null.
description_en	string	Tier description in English. Can be null.
remaining_for_next_tier	string	Amount (DH) still needed to reach the next Aksal Black tier. null when the customer is already at the highest tier or tier progression is not configured.
next_tier_labels	object	Labels of the next tier (label_fr, label_ar, label_en). null when there is no next tier.

Status Code: 404

Returned when no customer is found for the given identifier, the customer is not enrolled in Aksal Black, or no tier has been assigned yet.

{
  "detail": "No customer found."
}

{
  "detail": "No tier assigned for this card."
}

2) Black card challenges

Retrieve active challenges tagged for the Aksal Black program, along with each customer's remaining run window.

GET /api/v1/partner/aksal/black-card/<identifier>/challenges

Parameter	Type	Description
identifier	string	The Aksal Black card number or the customer's mobile phone number (see above)

Sample request (card number)

GET https://app.kenzup.com/api/v1/partner/aksal/black-card/AKSAL-BLACK-0001/challenges

Sample request (mobile phone number)

GET https://app.kenzup.com/api/v1/partner/aksal/black-card/0611223344/challenges

Status Code: 200

[
  {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name_fr": "Défi Aksal Black",
    "name_ar": "تحدي أكسال بلاك",
    "name_en": "Aksal Black Challenge",
    "description_fr": "Effectuez 3 achats en 48 heures.",
    "description_ar": "قم بـ 3 مشتريات خلال 48 ساعة.",
    "description_en": "Make 3 purchases within 48 hours.",
    "remaining_run_window_hours": 36.5,
    "bonus_amount": "50.00"
  }
]

Field	Type	Description
uuid	uuid	Challenge identifier
name_fr	string	Challenge name in French
name_ar	string	Challenge name in Arabic
name_en	string	Challenge name in English
description_fr	string	Challenge description in French. Can be null.
description_ar	string	Challenge description in Arabic. Can be null.
description_en	string	Challenge description in English. Can be null.
remaining_run_window_hours	decimal	Hours remaining in the customer's current run window. When the customer has no active in-progress run, this equals the challenge's configured run window duration.
bonus_amount	decimal	Points bonus awarded when the challenge is completed. 0 if no bonus is configured.

Only active challenges tagged with aksal_black (challenge tags) are returned. Returns an empty array when no matching challenges exist.

Status Code: 404

Returned when no customer is found for the given identifier or the customer is not enrolled in Aksal Black.

{
  "detail": "No customer found."
}

3) Black card history

Retrieve purchase history and spending statistics for an Aksal Black customer. Only approved sales at brands linked to the customer's tier are included.

GET /api/v1/partner/aksal/black-card/<identifier>/history

Parameter	Type	Description
identifier	string	The Aksal Black card number or the customer's mobile phone number (see above)

Sample request (card number)

GET https://app.kenzup.com/api/v1/partner/aksal/black-card/AKSAL-BLACK-0001/history

Sample request (mobile phone number)

GET https://app.kenzup.com/api/v1/partner/aksal/black-card/0611223344/history

Status Code: 200

{
  "total_sale_amount": "350.00",
  "total_sale_amount_current_year": "150.00",
  "total_sale_amount_current_month": "150.00",
  "number_of_purchases_current_year": 2,
  "number_of_purchases_current_month": 2,
  "history": [
    {
      "created_at": "2025-06-15T12:00:00Z",
      "brand_name": "Marjane",
      "shop_system_name": "marjane-casablanca-01",
      "earned_points": "10.00",
      "burned_points": "0.00"
    }
  ]
}

Field	Type	Description
total_sale_amount	decimal	Total approved sale amount across all time (tier brands only)
total_sale_amount_current_year	decimal	Total approved sale amount for the current calendar year
total_sale_amount_current_month	decimal	Total approved sale amount for the current calendar month
number_of_purchases_current_year	integer	Number of approved purchases in the current calendar year
number_of_purchases_current_month	integer	Number of approved purchases in the current calendar month
history	array	List of individual approved sales (see below)

Each item in history:

Field	Type	Description
created_at	datetime	Sale creation timestamp
brand_name	string	Brand name of the shop
shop_system_name	string	Shop system identifier
earned_points	decimal	Points earned on this sale
burned_points	decimal	Points burned on this sale

Status Code: 404

Returned when no customer is found for the given identifier, the customer is not enrolled in Aksal Black, or no tier has been assigned yet.

{
  "detail": "No customer found."
}

{
  "detail": "No tier assigned for this card."
}

Common errors

Status Code: 403

Returned when the signature is invalid or the client_id is not authorized.