Gift Endpoints

These endpoints handle gift-related operations including creating, viewing, updating, and managing gifts for courses and bundles.

List Gifts

Retrieve a list of gifts for the authenticated user.

Endpoint

GET /v1/customer/gifts

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer token	Yes

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "current_page": 1,
        "first_page_url": "http://testing-api.sumaya369.net/v1/customer/gifts?per_page=1&page=1",
        "from": 1,
        "last_page": 5,
        "last_page_url": "http://testing-api.sumaya369.net/v1/customer/gifts?per_page=1&page=5",
        "links": [
            {
                "url": null,
                "label": "&laquo; السابق",
                "active": false
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/customer/gifts?per_page=1&page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "http://testing-api.sumaya369.net/v1/customer/gifts?per_page=1&page=2",
                "label": "2",
                "active": false
            },
        ],
        "next_page_url": "http://testing-api.sumaya369.net/v1/customer/gifts?per_page=1&page=2",
        "path": "http://testing-api.sumaya369.net/v1/customer/gifts",
        "per_page": 1,
        "prev_page_url": null,
        "to": 1,
        "total": 5,
        "gifts": [
            {
                "id": "2c8fe950-98bf-11ee-b96b-05b489d1221c",
                "number": 2312131472,
                "product_name": "الفيل الأبيض",
                "from_customer": "Hamad Alshabanah",
                "to_customer": "--",
                "status": "completed",
                "type": "new",
                "gifted_to_email": "maram@elyak.com",
                "gifted_from_email": "developer@sumaya369.net",
                "is_gifted_to_unknown": false,
                "gift_to_unregistered_customer": true,
                "can_transfer_to_gar": true,
                "gift_hand": "محدد",
                "subscription_id": null,
                "subscription_ids": null,
                "order_id": null,
                "converted": null,
                "created_at": "01/01/2025"
            }
        ]
    },
    "status_code": 200
}

Create Gift

Create a new gift for a course or bundle.

Endpoint

POST /v1/customer/gifts

Request Parameters

Parameter	Type	Required	Description	Validation Rules
product_id	string	Yes	UUID or special ID of the course/bundle	Must be a valid UUID
product_type	string	Yes	Type of product (`course` or `bundle`)	Must be either 'course' or 'bundle'
type	string	Yes	Gift type	Must be either 'new' or 'convert'
is_gifted_to_unknown	boolean	No	Whether the gift is for an unknown recipient	Must be either true or false
gifted_to_email	string	Conditional	Email of the gift recipient	Required if is_gifted_to_unknown is false. Must be valid email format, 3-64 characters
is_messaged	boolean	Yes	Whether the gift includes a message	Must be either true or false
sender	string	Conditional	Name of the gift sender	Required if is_messaged is true. Max 32 characters
recipient	string	Conditional	Name of the gift recipient	Required if is_messaged is true. Max 32 characters
message	string	Conditional	Gift message	Required if is_messaged is true. 3-2500 characters
gifted_from_cart	boolean	No	Whether the gift is created from cart item	Must be true if specified

Success Response

{
    "success": true,
    "message": "تم حفظ البيانات بنجاح.",
    "data": {
        "gift_id": "c6b12f20-0474-11f0-a2c1-21b621da5442"
    },
    "status_code": 200
}

View Gift

Retrieve details of a specific gift.

Endpoint

GET /v1/customer/gifts/{id}

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "id": "2c8fe950-98bf-11ee-b96b-05b489d1221c",
        "product_name": "الفيل الأبيض",
        "type": "new",
        "status": "completed",
        "number": 2312131472,
        "gifted_to_email": "maram@elyak.com",
        "is_gifted_to_unknown": false,
        "is_messaged": false,
        "sender": null,
        "recipient": null,
        "message": null,
        "quantity": null,
        "customer_id": "9f2ecd22-5c07-48ec-9415-2979deec4493",
        "subscription_id": "44a7fb80-98bf-11ee-9f6f-0ba71cbde029",
        "order_id": "445b5370-98bf-11ee-aea6-27f513082053",
        "converted": false,
        "giftable_id": "019831f0-b67b-11ec-a1f8-1d8e8c44c894",
        "giftable_type": "App\\Models\\Course",
        "meta": null
    },
    "status_code": 200
}

Update Gift

Update an existing gift's details.

Endpoint

PUT /v1/customer/gifts/{id}

Request Parameters

Parameter	Type	Required	Description	Validation Rules
product_id	string	No	UUID or special ID of the course/bundle	Must be a valid UUID if provided
product_type	string	No	Type of product (`course` or `bundle`)	Must be either 'course' or 'bundle' if provided
type	string	No	Gift type	Must be either 'new' or 'convert' if provided
is_gifted_to_unknown	boolean	No	Whether the gift is for an unknown recipient	Must be either true or false
gifted_to_email	string	Conditional	Email of the gift recipient	Required if is_gifted_to_unknown is false. Must be valid email format, 3-64 characters
is_messaged	boolean	No	Whether the gift includes a message	Must be either true or false
sender	string	Conditional	Name of the gift sender	Required if is_messaged is true. Max 32 characters
recipient	string	Conditional	Name of the gift recipient	Required if is_messaged is true. Max 32 characters
message	string	Conditional	Gift message	Required if is_messaged is true. 3-2500 characters
gifted_from_cart	boolean	No	Whether the gift is created from cart item	Must be true if specified
cart_id	string	Conditional	ID of the cart item	Required if gifted_from_cart is true. Must be a valid UUID

Success Response

{
    "success": true,
    "message": "تم تحديث البيانات بنجاح.",
    "data": {
        "id": "c6b12f20-0474-11f0-a2c1-21b621da5442",
        "product_name": "طاقة الازمات",
        "type": "new",
        "status": "in cart",
        "number": null,
        "gifted_to_email": null,
        "is_gifted_to_unknown": true,
        "is_messaged": true,
        "sender": "Ahmed",
        "recipient": "Salem",
        "message": "hala walla",
        "quantity": null,
        "customer_id": "9f2ecd22-5c07-48ec-9415-2979deec4493",
        "subscription_id": null,
        "order_id": null,
        "converted": false,
        "giftable_id": "ed5d1a40-b67a-11ec-8630-a7dae8085a21",
        "giftable_type": "App\\Models\\Course",
        "meta": null
    },
    "status_code": 200
}

Delete Gift

Delete a gift and remove it from cart if present.

Endpoint

DELETE /v1/customer/gifts/{id}

Request Parameters

Parameter	Type	Required	Description	Validation Rules
ids	array	Yes	Array of gift IDs to delete	Required
ids.*	string	Yes	Gift ID	Must be a valid UUID

Success Response

{
    "success": true,
    "message": "تم حذف البيانات بنجاح.",
    "data": null,
    "status_code": 200
}

Check Gift Eligibility

Endpoint

POST /v1/customer/gifts/check-if-giftable

Request Parameters

Parameter	Type	Required	Description
product_id	string	Yes	UUID or special ID of the course/bundle
product_type	string	Yes	Type of product (`course` or `bundle`)
gifted_to_email	string	No	Email to check if can receive gift
gifted_from_cart	boolean	No	Whether checking for cart item gift
type	string	No	Gift type: `new` or `convert`

Success Response

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "messages": {
            "can_gift_to_customer_message": "الطرف الثاني لا يملك حساب في الموقع ، سنقوم بإرسال الهدية مع دعوة للتسجيل ، وستدرج المادة في حسابه فور التسجيل في الموقع",
            "can_gift_new_sub_message": "المتطلبات متوافقة",
            "can_gift_current_sub_message": "لايوجد لديك اشتراك نشط في هذا المادة . يمكنك أهداء اشتراك جديد"
        },
        "cases": {
            "can_gift_to_customer": true,
            "can_gift_new_sub": true,
            "can_gift_current_sub": false
        },
        "status_codes": [
            200,
            200,
            422
        ]
    },
    "status_code": 200
}

Eligibility Cases

Recipient Validation Cases

When gifted_to_email is provided:

Unregistered Customer
- Case: Email not found in system
- Result: Allowed (can_gift_to_customer = true)
- Status: 200
- Message: Gift to unregistered customer allowed
Self-Gifting
- Case: Gifted email matches sender's email
- Result: Not allowed (can_gift_to_customer = false)
- Status: 422
- Message: Cannot gift to self
Already Subscribed
- Case: Recipient already has subscription
- Result: Not allowed (can_gift_to_customer = false)
- Status: 422
- Message: Recipient already subscribed

New Gift Purchase Cases

Product Availability
- Case: Product not available for gifting
- Result: Not allowed (can_gift_new_sub = false)
- Status: 422
- Message: Product is closed for gifting
Free Product
- Case: Product price is 0
- Result: Not allowed (can_gift_new_sub = false)
- Status: 422
- Message: Cannot gift free products
Cart Conflict
- Case: Product already in cart without gifted_from_cart flag
- Result: Not allowed (can_gift_new_sub = false)
- Status: 422
- Message: Product already in cart
Valid New Gift
- Case: All requirements met
- Result: Allowed (can_gift_new_sub = true)
- Status: 200
- Message: Gift requirements match

Subscription Conversion Cases

No Active Subscription
- Case: User doesn't have active subscription
- Result: Not allowed (can_gift_current_sub = false)
- Status: 422
- Message: No valid subscription found
Bundle Course Validation
- Case: Bundle subscription with watched videos
- Result: Not allowed (can_gift_current_sub = false)
- Status: 422
- Message: Course in bundle has watched videos
Video Watch History
- Case: Subscription has watched videos
- Result: Not allowed (can_gift_current_sub = false)
- Status: 422
- Message: Subscription has watched videos
Product Settings
- Case: Product settings don't allow gifting
- Result: Not allowed (can_gift_current_sub = false)
- Status: 422
- Message: Product requirements not met
Valid Conversion
- Case: All requirements met
- Result: Allowed (can_gift_current_sub = true)
- Status: 200
- Message: Gift requirements match

Notes

All cases are checked independently
Multiple validation failures return first encountered error
Bundle gifting checks all included courses for eligibility
Status codes indicate success (200) or validation failure (422)

Implementation Details

Gift Status

Gifts can have the following statuses:

in_cart: Gift is added to cart but not purchased
completed: Gift has been purchased and processed

Gift Types

New Subscription Gift
- Creates a new gift from available products
- Requires payment
- No restrictions on gifting
Convert Subscription Gift
- Converts existing subscription to gift
- No additional payment required
- Has specific eligibility requirements:
  - Subscription must be active
  - No video views recorded
  - Product must allow gifting

Gift Messaging

Optional messaging feature controlled by is_messaged flag
When enabled, requires:
- Sender name (max 32 characters)
- Recipient name (max 32 characters)
- Message content (3-2500 characters)

Validation Rules

Cannot gift to self (same email)
Cannot gift to already subscribed users
Product must be available for gifting
Product must not be free
For conversion: subscription must meet eligibility criteria
Email validation follows strict format rules
All string inputs have maximum length restrictions

Special Cases

Gift to Unknown Recipient

Set is_gifted_to_unknown to true
No email validation required
Can be updated later with recipient email

Gift from Cart

Set gifted_from_cart to true
Links existing cart item to gift
Cannot add same product to cart again
Requires valid cart_id when updating

Bundle Gifting

When gifting bundles, all courses within the bundle are checked for eligibility
For conversion: all courses in bundle must meet conversion criteria

List Gifts​

Endpoint​

Request Headers​

Success Response​

Create Gift​

Endpoint​

Request Parameters​

Success Response​

View Gift​

Endpoint​

Success Response​

Update Gift​

Endpoint​

Request Parameters​

Success Response​

Delete Gift​

Endpoint​

Request Parameters​

Success Response​

Check Gift Eligibility​

Endpoint​

Request Parameters​

Success Response​

Eligibility Cases​

Recipient Validation Cases​

New Gift Purchase Cases​

Subscription Conversion Cases​

Notes​

Implementation Details​

Gift Status​

Gift Types​

Gift Messaging​

Validation Rules​

Special Cases​

Gift to Unknown Recipient​

Gift from Cart​

Bundle Gifting​

List Gifts

Endpoint

Request Headers

Success Response

Create Gift

Endpoint

Request Parameters

Success Response

View Gift

Endpoint

Success Response

Update Gift

Endpoint

Request Parameters

Success Response

Delete Gift

Endpoint

Request Parameters

Success Response

Check Gift Eligibility

Endpoint

Request Parameters

Success Response

Eligibility Cases

Recipient Validation Cases

New Gift Purchase Cases

Subscription Conversion Cases

Notes

Implementation Details

Gift Status

Gift Types

Gift Messaging

Validation Rules

Special Cases

Gift to Unknown Recipient

Gift from Cart

Bundle Gifting