Akinon Release Notes (11/10/2025) are now live! Click here to learn what's new.
Docs Portal

Loyalty Card

Get Loyalty Card Details

get

Retrieves the authenticated user's loyalty card information including available points balance.

This endpoint fetches both local loyalty card data and queries the external loyalty system for current points balance. Points are cached for 2 minutes to reduce external API calls.

Response Scenarios:

  • Success: Returns card details with points balance

  • No Card: Returns null card with 0 points

  • Points Query Failed: Returns card details with error message in errors field

Use Cases:

  • Display loyalty card information on account page

  • Show available points before checkout

  • Verify loyalty account status

  • Check points balance for redemption

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osssionid=abc123
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Responses
200

Successfully retrieved loyalty card details

application/json
get
/loyalty_card/
GET /loyalty-card/loyalty_card/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osssionid=abc123
Accept: */*

{
  "card": {
    "pk": 1,
    "attributes": {
      "account_number": "3839200"
    },
    "created_date": "2025-05-30T07:45:21.383195Z",
    "modified_date": "2025-05-30T07:45:21.383222Z",
    "number": "+966123457799",
    "user": {
      "pk": 92,
      "username": "fe710061d9d32af17b96f38bf49ee29655ae8b19682e10b1a8d02d6f79c35520",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "is_active": true,
      "date_joined": "2025-05-30T07:45:20.915321Z",
      "last_login": "2025-05-30T07:45:21.240293Z",
      "email_allowed": false,
      "sms_allowed": false,
      "call_allowed": null,
      "gender": "male",
      "attributes": {
        "confirmed": true,
        "logged_ip": "192.168.1.100",
        "verified_user": true,
        "register_client_type": "default"
      },
      "phone": "+966123457799",
      "date_of_birth": "1990-12-10",
      "attributes_kwargs": {},
      "user_type": "registered",
      "modified_date": "2025-05-30T07:45:21.812607Z"
    }
  },
  "points": 150,
  "errors": null
}

Get Current User Info for Loyalty Registration

get

Returns current user information for loyalty card registration form, or redirects if user already has a loyalty card.

Use Cases:

  • Pre-fill registration form with user data

  • Check if user already has loyalty card

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osssionid=abc123
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Responses
200

User information for registration form

application/json
get
/add_loyalty_card/
GET /loyalty-card/add_loyalty_card/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osssionid=abc123
Accept: */*

{
  "pk": 92,
  "username": "fe710061d9d32af17b96f38bf49ee29655ae8b19682e10b1a8d02d6f79c35520",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "is_active": true,
  "date_joined": "2025-05-30T07:45:20.915321Z",
  "last_login": "2025-05-30T07:45:21.240293Z",
  "email_allowed": false,
  "sms_allowed": false,
  "call_allowed": null,
  "gender": "male",
  "attributes": {
    "register_client_type": "default"
  },
  "phone": "+966123457799",
  "date_of_birth": "1990-12-10",
  "attributes_kwargs": {},
  "user_type": "registered",
  "modified_date": "2025-05-30T07:45:21.812607Z"
}

Register Loyalty Card with SMS Verification

post

Creates a loyalty card for the authenticated user with SMS verification flow.

SMS Verification Flow (when enabled):

  • First Request (without code):

    • Submit registration data without code field

    • System generates 4-digit verification code

    • SMS sent to provided phone number

    • Code stored in session as confirmation_data

    • Returns 202 Accepted with submitted data

  • Resend Request:

    • Submit same data with resend: true

    • New code generated and sent

    • Returns 200 OK with success message

  • Final Request (with code):

    • Submit complete data including code field

    • System validates phone and code match session

    • Creates loyalty account in external system

    • Creates local LoyaltyCard record

    • Sets user attributes: has_loyalty=true, verified_user=true

    • Optionally syncs user data if is_sync=true

    • Returns 201 Created with card details

Without SMS Verification:

  • If client has verify_sms=false, skips verification

  • Directly creates account on first request

  • Returns 201 Created immediately

Account Creation Logic:

  • Searches for existing account in external system first

  • If found, links existing account

  • If not found, creates new account

  • Local LoyaltyCard record always created

Configuration Dependencies:

  • CUSTOMER_LOYALTY_CARD_SERVICE must be configured

  • Client verify_sms attribute controls verification requirement

  • is_sync=true enables automatic user data sync

Use Cases:

  • New user loyalty card registration

  • SMS-verified account creation

  • Link existing external loyalty account

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Body
first_namestring · max: 30Required

User's first name

Example: John
last_namestring · max: 30Required

User's last name

Example: Doe
emailstring · emailRequired

User's email address

Example: [email protected]
email_allowedboolean | nullableOptional

Consent for email marketing

Default: falseExample: false
sms_allowedboolean | nullableOptional

Consent for SMS marketing

Default: falseExample: false
call_allowedboolean | nullableOptional

Consent for phone calls

Default: null
genderstring · enumRequired

Gender type enumeration.

Supported values:

  • male - Male
  • female - Female
  • unknown - Unknown/Prefer not to say
Example: malePossible values:
date_of_birthstring · dateRequired

User's date of birth (YYYY-MM-DD)

Example: 1990-12-10
phonestring · max: 60Required

Phone number in international format (E.164)

Example: +966123457799Pattern: ^\+?1?\d{9,15}$
codestring · min: 4 · max: 20Optional

SMS verification code (required on second submission)

Example: 1234
resendbooleanOptional

Request to resend SMS verification code

Default: falseExample: false
Responses
200

SMS verification code resent successfully

application/json
post
/add_loyalty_card/
POST /loyalty-card/add_loyalty_card/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osessionid=abc123; csrftoken=def456
X-Csrftoken: def456
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "gender": "male",
  "date_of_birth": "1990-12-10",
  "phone": "+966123457799",
  "email_allowed": false,
  "sms_allowed": false
}
{
  "message": "success"
}

Register Loyalty Card Without SMS Verification

post

Creates a loyalty card for users who have already completed OTP verification through other means.

This endpoint bypasses SMS verification and directly creates the loyalty account. It's intended for scenarios where:

  • User already verified during registration

  • Verification handled by external system

  • SMS verification not required for loyalty enrollment

Account Creation Process:

  • Validates submitted data

  • Creates loyalty account in external system (or links existing)

  • Creates local LoyaltyCard record

  • Sets user attribute: has_loyalty=true

  • Optionally syncs user data if is_sync=true

Differences from Standard Registration:

  • No SMS verification step

  • Does not set verified_user attribute

  • Single-step process (no session state)

  • No code validation

Use Cases:

  • Post-registration loyalty enrollment

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Body
all ofOptional
Responses
post
/add_loyalty_card_otp/
POST /loyalty-card/add_loyalty_card_otp/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osessionid=abc123; csrftoken=def456
X-Csrftoken: def456
Content-Type: application/json
Accept: */*
Content-Length: 200

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "gender": "male",
  "date_of_birth": "1990-12-10",
  "phone": "+966123457799",
  "email_allowed": false,
  "sms_allowed": true,
  "call_allowed": null
}
{
  "card": {
    "pk": 2,
    "attributes": {
      "account_number": "3839201"
    },
    "created_date": "2025-06-01T10:20:15.123456Z",
    "modified_date": "2025-06-01T10:20:15.123456Z",
    "number": "+966123457799",
    "user": {
      "pk": 93,
      "username": "8f21a0a7c3e4b2d9f1e7c8a4b6d5f3e2a1c9b7d8e6f4a3c2b1d9e8f7a6b5c4d3",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "is_active": true,
      "date_joined": "2025-06-01T10:15:00.000000Z",
      "last_login": "2025-06-01T10:15:30.000000Z",
      "email_allowed": false,
      "sms_allowed": true,
      "call_allowed": null,
      "gender": "male",
      "attributes": {
        "has_loyalty": true,
        "register_client_type": "default"
      },
      "phone": "+966123457799",
      "date_of_birth": "1990-12-10",
      "attributes_kwargs": {},
      "user_type": "registered",
      "modified_date": "2025-06-01T10:20:15.500000Z"
    }
  },
  "redirect_url": "omnishop_loyaltycard:loyalty-card"
}

Get Current Loyalty Card Info for Update

get

Retrieves current loyalty card information from external system for update form.

Use Cases:

  • Display current loyalty card info before update

  • Pre-fill update form with existing values

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osssionid=abc123
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Responses
200

Current loyalty card information from external system

application/json
get
/update_loyalty_card/
GET /loyalty-card/update_loyalty_card/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osssionid=abc123
Accept: */*

{
  "card": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+966123457799",
    "email": "[email protected]",
    "gender": "male",
    "date_of_birth": "1990-12-10",
    "email_allowed": false,
    "sms_allowed": true,
    "call_allowed": null
  }
}

Update Loyalty Card Information

post

Updates loyalty card information in both external system and local database.

Synchronization:

  • If is_sync=true in config, updates local user profile

  • Synchronizes: first_name, last_name, phone, gender, date_of_birth, preferences

  • External system always updated

Use Cases:

  • Update contact information

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Body
phonestring · max: 60Required

Phone number (must be unique, cannot match other active users)

Example: +966123457799Pattern: ^\+?1?\d{9,15}$
first_namestring · max: 30Required

User's first name

Example: John
last_namestring · max: 30Required

User's last name

Example: Doe
email_allowedboolean | nullableOptional

Consent for email marketing

Default: falseExample: false
sms_allowedboolean | nullableOptional

Consent for SMS marketing

Default: falseExample: true
call_allowedboolean | nullableOptional

Consent for phone calls

Default: null
genderstring · enumRequired

Gender type enumeration.

Supported values:

  • male - Male
  • female - Female
  • unknown - Unknown/Prefer not to say
Example: malePossible values:
date_of_birthstring · date | nullableOptional

User's date of birth

Example: 1990-12-10
Responses
200

Loyalty card successfully updated

application/json
post
/update_loyalty_card/
POST /loyalty-card/update_loyalty_card/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osessionid=abc123; csrftoken=def456
X-Csrftoken: def456
Content-Type: application/json
Accept: */*
Content-Length: 172

{
  "phone": "+966123457799",
  "first_name": "John",
  "last_name": "Smith",
  "email_allowed": false,
  "sms_allowed": true,
  "call_allowed": false,
  "gender": "male",
  "date_of_birth": "1990-12-10"
}
{
  "card": {
    "phone": "+966123457799",
    "first_name": "John",
    "last_name": "Smith",
    "email_allowed": false,
    "sms_allowed": true,
    "call_allowed": false,
    "gender": "male",
    "date_of_birth": "1990-12-10"
  },
  "redirect_url": "omnishop_loyaltycard:loyalty-card"
}

Get Loyalty Card Info for Deletion Confirmation

get

Retrieves loyalty card information for deletion confirmation screen.

Use Cases:

  • Display card info before deletion

  • Confirmation screen data

  • Verify card to be deleted

Header parameters
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Responses
200

Loyalty card information for deletion confirmation

application/json
get
/delete_loyalty/
GET /loyalty-card/delete_loyalty/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

{
  "card": {
    "pk": 1,
    "attributes": {
      "account_number": "3839200"
    },
    "created_date": "2025-05-30T07:45:21.383195Z",
    "modified_date": "2025-05-30T07:45:21.383222Z",
    "number": "+966123457799",
    "user": {
      "pk": 92,
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+966123457799"
    }
  }
}

Delete Loyalty Card

post

Deletes the user's loyalty card from the local database.

Deletion Process:

  • Retrieves user's loyalty card

  • Optionally notifies external system (implementation-dependent)

  • Deletes local LoyaltyCard record

  • Returns 204 No Content on success

Important Notes:

  • Local LoyaltyCard record always deleted

  • External account may or may not be deactivated (depends on implementation)

  • User attributes (has_loyalty) not automatically cleared

  • Action is irreversible

Post-Deletion State:

  • User no longer has loyalty card in local system

  • Cannot query points or use points

  • Can create new loyalty card later

Use Cases:

  • User requests account deletion

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Responses
post
/delete_loyalty/
POST /loyalty-card/delete_loyalty/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osessionid=abc123; csrftoken=def456
X-Csrftoken: def456
Accept: */*

No content

Search for Existing Loyalty Account and Link

post

Searches for an existing loyalty account in the external system and creates a local LoyaltyCard link if found.

Search Process:

  1. Queries external loyalty system with provided criteria

  2. If account found, creates local LoyaltyCard record

  3. Links local user to external loyalty account

  4. Sets user attribute: has_loyalty=true

  5. Returns card number on success

Search Criteria:

  • Email (required): Primary search field

  • Phone (optional): Additional matching criterion

  • Date of birth (optional): Additional matching criterion

  • Multiple fields improve match accuracy

Response Scenarios:

  • Account Found (201): Local card created, returns number

  • Account Not Found (200): No match in external system, returns message

No Account Creation:

  • This endpoint only links existing accounts

  • Does not create new external loyalty accounts

  • If account not found, user must use registration endpoints

Use Cases:

  • Link existing loyalty account during first login

  • Migrate users from external system

  • Connect pre-existing loyalty members

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Body
phonestring · max: 60Optional

Phone number to search for

Example: +966123457799Pattern: ^\+?1?\d{9,15}$
emailstring · emailRequired

Email address to search for (required)

Example: [email protected]
date_of_birthstring · dateOptional

Date of birth for additional matching

Example: 1990-12-10
Responses
200

No existing account found in external system

application/json
post
/search_exists_create/
POST /loyalty-card/search_exists_create/ HTTP/1.1
Host: sandbox.akinon.com
X-Cookie: osessionid=abc123; csrftoken=def456
X-Csrftoken: def456
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "email": "[email protected]",
  "phone": "+966123457799"
}
{
  "message": "not find remote account"
}
PreviousUser AttributesNextModels

Last updated

Was this helpful?