> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/loyalty-card/loyalty-card.md).

# Loyalty Card

## Get Loyalty Card Details

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/loyalty_card/":{"get":{"summary":"Get Loyalty Card Details","description":"Retrieves the authenticated user's loyalty card information including available points balance.\n\nThis 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.\n\n**Response Scenarios:**\n* **Success**: Returns card details with points balance\n* **No Card**: Returns null card with 0 points\n* **Points Query Failed**: Returns card details with error message in `errors` field\n\n**Use Cases:**\n* Display loyalty card information on account page\n* Show available points before checkout\n* Verify loyalty account status\n* Check points balance for redemption","operationId":"get_loyalty_card","parameters":[{"$ref":"#/components/parameters/CookieHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"Successfully retrieved loyalty card details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyCardResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"LoyaltyCardResponse":{"type":"object","properties":{"card":{"allOf":[{"$ref":"#/components/schemas/LoyaltyCard"},{"nullable":true}],"description":"Loyalty card details (null if not found)"},"points":{"type":"number","format":"float","description":"Available loyalty points balance (decimal value)"},"errors":{"type":"string","nullable":true,"description":"Error message if points query failed"}}},"LoyaltyCard":{"type":"object","properties":{"pk":{"type":"integer","description":"Loyalty card unique identifier"},"attributes":{"type":"object","description":"Custom loyalty card attributes (EAV)","additionalProperties":true},"created_date":{"type":"string","format":"date-time","description":"Loyalty card creation date"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"},"number":{"type":"string","description":"Loyalty card number (typically phone number)"},"user":{"$ref":"#/components/schemas/UserDetail"}}},"UserDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"User unique identifier"},"username":{"type":"string","description":"Hashed username for privacy"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"is_active":{"type":"boolean","description":"Whether the user account is active"},"date_joined":{"type":"string","format":"date-time","description":"User registration date"},"last_login":{"type":"string","format":"date-time","nullable":true,"description":"Last login timestamp"},"email_allowed":{"type":"boolean","description":"User consent for email marketing"},"sms_allowed":{"type":"boolean","description":"User consent for SMS marketing"},"call_allowed":{"type":"boolean","nullable":true,"description":"User consent for phone calls"},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"attributes":{"type":"object","description":"Custom user attributes (EAV)","additionalProperties":true},"phone":{"type":"string","description":"User's phone number in international format"},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"User's date of birth"},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata"},"user_type":{"type":"string","description":"Type of user account"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"}}},"GenderTypeEnum":{"type":"string","description":"Gender type enumeration.\n\nSupported values:\n* `male` - Male\n* `female` - Female\n* `unknown` - Unknown/Prefer not to say","enum":["male","female","unknown"]},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Get Current User Info for Loyalty Registration

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/add_loyalty_card/":{"get":{"summary":"Get Current User Info for Loyalty Registration","description":"Returns current user information for loyalty card registration form, or redirects if user already has a loyalty card.\n\n**Use Cases:**\n* Pre-fill registration form with user data\n* Check if user already has loyalty card","operationId":"get_add_loyalty_card_form","parameters":[{"$ref":"#/components/parameters/CookieHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"User information for registration form","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDetail"}}}},"302":{"description":"Redirect to loyalty-card page (user already has card)"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"UserDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"User unique identifier"},"username":{"type":"string","description":"Hashed username for privacy"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"is_active":{"type":"boolean","description":"Whether the user account is active"},"date_joined":{"type":"string","format":"date-time","description":"User registration date"},"last_login":{"type":"string","format":"date-time","nullable":true,"description":"Last login timestamp"},"email_allowed":{"type":"boolean","description":"User consent for email marketing"},"sms_allowed":{"type":"boolean","description":"User consent for SMS marketing"},"call_allowed":{"type":"boolean","nullable":true,"description":"User consent for phone calls"},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"attributes":{"type":"object","description":"Custom user attributes (EAV)","additionalProperties":true},"phone":{"type":"string","description":"User's phone number in international format"},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"User's date of birth"},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata"},"user_type":{"type":"string","description":"Type of user account"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"}}},"GenderTypeEnum":{"type":"string","description":"Gender type enumeration.\n\nSupported values:\n* `male` - Male\n* `female` - Female\n* `unknown` - Unknown/Prefer not to say","enum":["male","female","unknown"]},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Register Loyalty Card with SMS Verification

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/add_loyalty_card/":{"post":{"summary":"Register Loyalty Card with SMS Verification","description":"Creates a loyalty card for the authenticated user with SMS verification flow.\n\n**SMS Verification Flow (when enabled):**\n\n- **First Request (without code):**\n   - Submit registration data without `code` field\n   - System generates 4-digit verification code\n   - SMS sent to provided phone number\n   - Code stored in session as `confirmation_data`\n   - Returns 202 Accepted with submitted data\n\n- **Resend Request:**\n   - Submit same data with `resend: true`\n   - New code generated and sent\n   - Returns 200 OK with success message\n\n- **Final Request (with code):**\n   - Submit complete data including `code` field\n   - System validates phone and code match session\n   - Creates loyalty account in external system\n   - Creates local LoyaltyCard record\n   - Sets user attributes: `has_loyalty=true`, `verified_user=true`\n   - Optionally syncs user data if `is_sync=true`\n   - Returns 201 Created with card details\n\n**Without SMS Verification:**\n* If client has `verify_sms=false`, skips verification\n* Directly creates account on first request\n* Returns 201 Created immediately\n\n**Account Creation Logic:**\n* Searches for existing account in external system first\n* If found, links existing account\n* If not found, creates new account\n* Local LoyaltyCard record always created\n\n**Configuration Dependencies:**\n* `CUSTOMER_LOYALTY_CARD_SERVICE` must be configured\n* Client `verify_sms` attribute controls verification requirement\n* `is_sync=true` enables automatic user data sync\n\n**Use Cases:**\n* New user loyalty card registration\n* SMS-verified account creation\n* Link existing external loyalty account","operationId":"add_loyalty_card","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterLoyaltyCardRequest"}}}},"responses":{"200":{"description":"SMS verification code resent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"201":{"description":"Loyalty card successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterLoyaltyCardResponse"}}}},"202":{"description":"SMS verification code sent, awaiting verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterLoyaltyCardRequest"}}}},"400":{"description":"Validation error or verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"RegisterLoyaltyCardRequest":{"type":"object","required":["first_name","last_name","email","gender","date_of_birth","phone"],"properties":{"first_name":{"type":"string","maxLength":30,"description":"User's first name"},"last_name":{"type":"string","maxLength":30,"description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"email_allowed":{"type":"boolean","nullable":true,"description":"Consent for email marketing","default":false},"sms_allowed":{"type":"boolean","nullable":true,"description":"Consent for SMS marketing","default":false},"call_allowed":{"type":"boolean","nullable":true,"description":"Consent for phone calls","default":null},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"date_of_birth":{"type":"string","format":"date","description":"User's date of birth (YYYY-MM-DD)"},"phone":{"type":"string","pattern":"^\\+?1?\\d{9,15}$","maxLength":60,"description":"Phone number in international format (E.164)"},"code":{"type":"string","minLength":4,"maxLength":20,"description":"SMS verification code (required on second submission)"},"resend":{"type":"boolean","description":"Request to resend SMS verification code","default":false}}},"GenderTypeEnum":{"type":"string","description":"Gender type enumeration.\n\nSupported values:\n* `male` - Male\n* `female` - Female\n* `unknown` - Unknown/Prefer not to say","enum":["male","female","unknown"]},"MessageResponse":{"type":"object","properties":{"message":{"type":"string","description":"Response message"}}},"RegisterLoyaltyCardResponse":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/LoyaltyCard"},"redirect_url":{"type":"string","description":"URL to redirect after successful registration"}}},"LoyaltyCard":{"type":"object","properties":{"pk":{"type":"integer","description":"Loyalty card unique identifier"},"attributes":{"type":"object","description":"Custom loyalty card attributes (EAV)","additionalProperties":true},"created_date":{"type":"string","format":"date-time","description":"Loyalty card creation date"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"},"number":{"type":"string","description":"Loyalty card number (typically phone number)"},"user":{"$ref":"#/components/schemas/UserDetail"}}},"UserDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"User unique identifier"},"username":{"type":"string","description":"Hashed username for privacy"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"is_active":{"type":"boolean","description":"Whether the user account is active"},"date_joined":{"type":"string","format":"date-time","description":"User registration date"},"last_login":{"type":"string","format":"date-time","nullable":true,"description":"Last login timestamp"},"email_allowed":{"type":"boolean","description":"User consent for email marketing"},"sms_allowed":{"type":"boolean","description":"User consent for SMS marketing"},"call_allowed":{"type":"boolean","nullable":true,"description":"User consent for phone calls"},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"attributes":{"type":"object","description":"Custom user attributes (EAV)","additionalProperties":true},"phone":{"type":"string","description":"User's phone number in international format"},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"User's date of birth"},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata"},"user_type":{"type":"string","description":"Type of user account"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Register Loyalty Card Without SMS Verification

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/add_loyalty_card_otp/":{"post":{"summary":"Register Loyalty Card Without SMS Verification","description":"Creates a loyalty card for users who have already completed OTP verification through other means.\n\nThis endpoint bypasses SMS verification and directly creates the loyalty account. It's intended for scenarios where:\n* User already verified during registration\n* Verification handled by external system\n* SMS verification not required for loyalty enrollment\n\n**Account Creation Process:**\n- Validates submitted data\n- Creates loyalty account in external system (or links existing)\n- Creates local LoyaltyCard record\n- Sets user attribute: `has_loyalty=true`\n- Optionally syncs user data if `is_sync=true`\n\n**Differences from Standard Registration:**\n* No SMS verification step\n* Does not set `verified_user` attribute\n* Single-step process (no session state)\n* No code validation\n\n**Use Cases:**\n* Post-registration loyalty enrollment","operationId":"add_loyalty_card_otp","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RegisterLoyaltyCardRequest"},{"type":"object","description":"Same as standard registration but without code/resend fields"}]}}}},"responses":{"201":{"description":"Loyalty card successfully created without SMS verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterLoyaltyCardResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"RegisterLoyaltyCardRequest":{"type":"object","required":["first_name","last_name","email","gender","date_of_birth","phone"],"properties":{"first_name":{"type":"string","maxLength":30,"description":"User's first name"},"last_name":{"type":"string","maxLength":30,"description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"email_allowed":{"type":"boolean","nullable":true,"description":"Consent for email marketing","default":false},"sms_allowed":{"type":"boolean","nullable":true,"description":"Consent for SMS marketing","default":false},"call_allowed":{"type":"boolean","nullable":true,"description":"Consent for phone calls","default":null},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"date_of_birth":{"type":"string","format":"date","description":"User's date of birth (YYYY-MM-DD)"},"phone":{"type":"string","pattern":"^\\+?1?\\d{9,15}$","maxLength":60,"description":"Phone number in international format (E.164)"},"code":{"type":"string","minLength":4,"maxLength":20,"description":"SMS verification code (required on second submission)"},"resend":{"type":"boolean","description":"Request to resend SMS verification code","default":false}}},"GenderTypeEnum":{"type":"string","description":"Gender type enumeration.\n\nSupported values:\n* `male` - Male\n* `female` - Female\n* `unknown` - Unknown/Prefer not to say","enum":["male","female","unknown"]},"RegisterLoyaltyCardResponse":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/LoyaltyCard"},"redirect_url":{"type":"string","description":"URL to redirect after successful registration"}}},"LoyaltyCard":{"type":"object","properties":{"pk":{"type":"integer","description":"Loyalty card unique identifier"},"attributes":{"type":"object","description":"Custom loyalty card attributes (EAV)","additionalProperties":true},"created_date":{"type":"string","format":"date-time","description":"Loyalty card creation date"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"},"number":{"type":"string","description":"Loyalty card number (typically phone number)"},"user":{"$ref":"#/components/schemas/UserDetail"}}},"UserDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"User unique identifier"},"username":{"type":"string","description":"Hashed username for privacy"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"is_active":{"type":"boolean","description":"Whether the user account is active"},"date_joined":{"type":"string","format":"date-time","description":"User registration date"},"last_login":{"type":"string","format":"date-time","nullable":true,"description":"Last login timestamp"},"email_allowed":{"type":"boolean","description":"User consent for email marketing"},"sms_allowed":{"type":"boolean","description":"User consent for SMS marketing"},"call_allowed":{"type":"boolean","nullable":true,"description":"User consent for phone calls"},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"attributes":{"type":"object","description":"Custom user attributes (EAV)","additionalProperties":true},"phone":{"type":"string","description":"User's phone number in international format"},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"User's date of birth"},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata"},"user_type":{"type":"string","description":"Type of user account"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Get Current Loyalty Card Info for Update

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/update_loyalty_card/":{"get":{"summary":"Get Current Loyalty Card Info for Update","description":"Retrieves current loyalty card information from external system for update form.\n\n**Use Cases:**\n* Display current loyalty card info before update\n* Pre-fill update form with existing values","operationId":"get_update_loyalty_card_form","parameters":[{"$ref":"#/components/parameters/CookieHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"Current loyalty card information from external system","content":{"application/json":{"schema":{"type":"object","properties":{"card":{"type":"object","description":"Current card information from external system"}}}}}},"302":{"description":"Redirect to loyalty-card page (no card exists)"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Update Loyalty Card Information

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/update_loyalty_card/":{"post":{"summary":"Update Loyalty Card Information","description":"Updates loyalty card information in both external system and local database.\n\n**Synchronization:**\n* If `is_sync=true` in config, updates local user profile\n* Synchronizes: first_name, last_name, phone, gender, date_of_birth, preferences\n* External system always updated\n\n**Use Cases:**\n* Update contact information","operationId":"update_loyalty_card","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLoyaltyCardRequest"}}}},"responses":{"200":{"description":"Loyalty card successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLoyaltyCardResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User has no loyalty card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"UpdateLoyaltyCardRequest":{"type":"object","required":["phone","first_name","last_name","gender"],"properties":{"phone":{"type":"string","pattern":"^\\+?1?\\d{9,15}$","maxLength":60,"description":"Phone number (must be unique, cannot match other active users)"},"first_name":{"type":"string","maxLength":30,"description":"User's first name"},"last_name":{"type":"string","maxLength":30,"description":"User's last name"},"email_allowed":{"type":"boolean","nullable":true,"description":"Consent for email marketing","default":false},"sms_allowed":{"type":"boolean","nullable":true,"description":"Consent for SMS marketing","default":false},"call_allowed":{"type":"boolean","nullable":true,"description":"Consent for phone calls","default":null},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"User's date of birth"}}},"GenderTypeEnum":{"type":"string","description":"Gender type enumeration.\n\nSupported values:\n* `male` - Male\n* `female` - Female\n* `unknown` - Unknown/Prefer not to say","enum":["male","female","unknown"]},"UpdateLoyaltyCardResponse":{"type":"object","properties":{"card":{"type":"object","description":"Updated loyalty card information","properties":{"phone":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email_allowed":{"type":"boolean"},"sms_allowed":{"type":"boolean"},"call_allowed":{"type":"boolean","nullable":true},"gender":{"type":"string"},"date_of_birth":{"type":"string","format":"date"}}},"redirect_url":{"type":"string","description":"URL to redirect after successful update"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Get Loyalty Card Info for Deletion Confirmation

> Retrieves loyalty card information for deletion confirmation screen.\
> \
> \*\*Use Cases:\*\*\
> \* Display card info before deletion\
> \* Confirmation screen data\
> \* Verify card to be deleted

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/delete_loyalty/":{"get":{"summary":"Get Loyalty Card Info for Deletion Confirmation","description":"Retrieves loyalty card information for deletion confirmation screen.\n\n**Use Cases:**\n* Display card info before deletion\n* Confirmation screen data\n* Verify card to be deleted","operationId":"get_delete_loyalty_card_confirmation","parameters":[{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"Loyalty card information for deletion confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"card":{"$ref":"#/components/schemas/LoyaltyCard"}}}}}},"302":{"description":"Redirect to loyalty-card page (no card exists)"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"LoyaltyCard":{"type":"object","properties":{"pk":{"type":"integer","description":"Loyalty card unique identifier"},"attributes":{"type":"object","description":"Custom loyalty card attributes (EAV)","additionalProperties":true},"created_date":{"type":"string","format":"date-time","description":"Loyalty card creation date"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"},"number":{"type":"string","description":"Loyalty card number (typically phone number)"},"user":{"$ref":"#/components/schemas/UserDetail"}}},"UserDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"User unique identifier"},"username":{"type":"string","description":"Hashed username for privacy"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"is_active":{"type":"boolean","description":"Whether the user account is active"},"date_joined":{"type":"string","format":"date-time","description":"User registration date"},"last_login":{"type":"string","format":"date-time","nullable":true,"description":"Last login timestamp"},"email_allowed":{"type":"boolean","description":"User consent for email marketing"},"sms_allowed":{"type":"boolean","description":"User consent for SMS marketing"},"call_allowed":{"type":"boolean","nullable":true,"description":"User consent for phone calls"},"gender":{"$ref":"#/components/schemas/GenderTypeEnum"},"attributes":{"type":"object","description":"Custom user attributes (EAV)","additionalProperties":true},"phone":{"type":"string","description":"User's phone number in international format"},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"User's date of birth"},"attributes_kwargs":{"type":"object","description":"Additional attribute metadata"},"user_type":{"type":"string","description":"Type of user account"},"modified_date":{"type":"string","format":"date-time","description":"Last modification date"}}},"GenderTypeEnum":{"type":"string","description":"Gender type enumeration.\n\nSupported values:\n* `male` - Male\n* `female` - Female\n* `unknown` - Unknown/Prefer not to say","enum":["male","female","unknown"]},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Delete Loyalty Card

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/delete_loyalty/":{"post":{"summary":"Delete Loyalty Card","description":"Deletes the user's loyalty card from the local database.\n\n**Deletion Process:**\n- Retrieves user's loyalty card\n- Optionally notifies external system (implementation-dependent)\n- Deletes local LoyaltyCard record\n- Returns 204 No Content on success\n\n**Important Notes:**\n* Local LoyaltyCard record always deleted\n* External account may or may not be deactivated (depends on implementation)\n* User attributes (`has_loyalty`) not automatically cleared\n* Action is irreversible\n\n**Post-Deletion State:**\n* User no longer has loyalty card in local system\n* Cannot query points or use points\n* Can create new loyalty card later\n\n**Use Cases:**\n* User requests account deletion","operationId":"delete_loyalty_card","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"204":{"description":"Loyalty card successfully deleted (no content returned)"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User has no loyalty card to delete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Search for Existing Loyalty Account and Link

> 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

```json
{"openapi":"3.0.3","info":{"title":"Loyalty Card API","version":"1.0.0"},"servers":[{"description":"Server base URL for loyalty card operations","url":"https://{commerce_url}/loyalty-card","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/search_exists_create/":{"post":{"summary":"Search for Existing Loyalty Account and Link","description":"Searches for an existing loyalty account in the external system and creates a local LoyaltyCard link if found.\n\n**Search Process:**\n1. Queries external loyalty system with provided criteria\n2. If account found, creates local LoyaltyCard record\n3. Links local user to external loyalty account\n4. Sets user attribute: `has_loyalty=true`\n5. Returns card number on success\n\n**Search Criteria:**\n* Email (required): Primary search field\n* Phone (optional): Additional matching criterion\n* Date of birth (optional): Additional matching criterion\n* Multiple fields improve match accuracy\n\n**Response Scenarios:**\n* **Account Found (201)**: Local card created, returns number\n* **Account Not Found (200)**: No match in external system, returns message\n\n**No Account Creation:**\n* This endpoint only links existing accounts\n* Does not create new external loyalty accounts\n* If account not found, user must use registration endpoints\n\n**Use Cases:**\n* Link existing loyalty account during first login\n* Migrate users from external system\n* Connect pre-existing loyalty members","operationId":"search_exists_create","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchExistsCreateRequest"}}}},"responses":{"200":{"description":"No existing account found in external system","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"201":{"description":"Existing account found and local card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchExistsCreateResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["loyalty-card"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"SearchExistsCreateRequest":{"type":"object","required":["email"],"properties":{"phone":{"type":"string","pattern":"^\\+?1?\\d{9,15}$","maxLength":60,"description":"Phone number to search for"},"email":{"type":"string","format":"email","description":"Email address to search for (required)"},"date_of_birth":{"type":"string","format":"date","description":"Date of birth for additional matching"}}},"NotFoundResponse":{"type":"object","properties":{"message":{"type":"string","description":"Message indicating account not found"}}},"SearchExistsCreateResponse":{"type":"object","properties":{"number":{"type":"string","description":"Created loyalty card number"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/loyalty-card/loyalty-card.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.