Cart API Specification¶

Overview¶

The Cart API provides endpoints for managing shopping carts, including creation, item management, and checkout operations.

Base Path: /cart

Content Types: - Request: application/json - Response: application/json

Response Format¶

All endpoints return a TlinqApiResponse object:

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

Date Format: All dates are returned in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss)

Endpoints¶

POST /cart/create¶

Creates a new shopping cart.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User/browser session token | | persistent | boolean | No | Whether the cart should be persistent (default: false) |

Request Example:

{
  "session": "user-session-token",
  "persistent": false
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sessionId": "user-session-token",
    "items": [],
    "paymentRef": null,
    "paymentUrl": null,
    "orderNum": null
  }
}

Error Codes: - MISSING_PARAMETER - Session ID not provided

POST /cart/load¶

Loads an existing cart for the session.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User/browser session token |

Request Example:

{
  "session": "user-session-token"
}

Response Structure:

href="#__codelineno-4-1">{ "apiStatus": { "errorCode": "OK", "errorMessage": "Success" }, "apiData": { "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "sessionId": "user-session-token", "items": [ { "itemId": 0, "cartItemId": "client-item-001", "productId": 1234, "productTemplateId": 100, "unitId": 5678, "unitName": "Desert Safari Premium", "description": "Premium Desert Safari with BBQ Dinner", "unitPrice": 150.00, "quantity": 2.0, "child": false, "infant": false, "bookDate": "2025-06-20T00:00:00", "extAttr": null, "extVariantId": null, "pickupLocation": "Dubai Mall", "serviceLocation": "Dubai Desert", "xferType": "SIC", "timeSlot": "15:00-21:00", "startTime": "15:00", "isAvailable": true, "ppc": 100.00, "resvName": "John Smith" } ], "paymentRef": null, "paymentUrl": null, "orderNum": null } }

Error Codes: - MISSING_PARAMETER - Session ID not provided

POST /cart/addItem¶

Adds one or more items to the cart.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | items | array | Yes | Array of cart items to add |

Item Object: | Field | Type | Required | Description | |-------|------|----------|-------------| | cartItemId | string | No | Client-side item identifier for tracking | | productId | integer | Yes | Product ID | | productTemplateId | integer | No | Product template ID | | unitId | integer | Yes | Unit/variant ID | | unitName | string | No | Unit name for display | | description | string | No | Item description | | unitPrice | number | Yes | Price per unit | | quantity | number | Yes | Quantity to add | | isChild | boolean | No | Whether this is a child ticket | | isInfant | boolean | No | Whether this is an infant ticket | | bookDate | string | No | Booking date (yyyy-MM-dd) | | extAttr | string | No | Extended attributes JSON | | extVariantId | integer | No | External variant ID | | pickupLocation | string | No | Pickup location | | serviceLocation | string | No | Service location | | xferType | string | No | Transfer type (SIC, PVT) | | timeSlot | string | No | Selected time slot | | startTime | string | No | Start time | | ppc | number | No | Purchase price for cost tracking | | resvName | string | No | Reservation name |

Request Example:

{
  "session": "user-session-token",
  "items": [
    {
      "cartItemId": "client-item-001",
      "productId": 1234,
      "unitId": 5678,
      "unitName": "Adult Ticket",
      "description": "Desert Safari Premium Experience",
      "unitPrice": 150.00,
      "quantity": 2,
      "isChild": false,
      "bookDate": "2025-06-20",
      "pickupLocation": "Dubai Mall",
      "timeSlot": "15:00-21:00",
      "resvName": "John Smith"
    },
    {
      "cartItemId": "client-item-002",
      "productId": 1234,
      "unitId": 5679,
      "unitName": "Child Ticket",
      "description": "Desert Safari Premium Experience - Child",
      "unitPrice": 100.00,
      "quantity": 1,
      "isChild": true,
      "bookDate": "2025-06-20",
      "pickupLocation": "Dubai Mall",
      "timeSlot": "15:00-21:00"
    }
  ]
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "itemId": 0,
      "cartItemId": "client-item-001"
    },
    {
      "itemId": 1,
      "cartItemId": "client-item-002"
    }
  ]
}

Error Codes: - MISSING_PARAMETER - Session ID or item list not provided - TOKEN_ERROR - Session not recognized

POST /cart/removeItem¶

Removes an item from the cart.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | itemId | integer | No | Server-assigned item ID | | cartItemId | string | No | Client-side item identifier |

*Either itemId or cartItemId must be provided.

Request Example:

{
  "session": "user-session-token",
  "itemId": 0
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": null
}

Error Codes: - MISSING_PARAMETER - Session ID or item ID not provided - TOKEN_ERROR - Session not recognized

POST /cart/updateItem¶

Updates the quantity of an item in the cart.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | itemId | integer | No | Server-assigned item ID | | cartItemId | string | No | Client-side item identifier | | quantity | number | Yes | New quantity for the item |

*Either itemId or cartItemId must be provided.

Request Example:

{
  "session": "user-session-token",
  "itemId": 0,
  "quantity": 3
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": null
}

Error Codes: - MISSING_PARAMETER - Session ID, item ID, or quantity not provided - TOKEN_ERROR - Session not recognized

POST /cart/persist¶

Converts a transient cart to a persistent cart (for logged-in users).

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | New user session token (logged-in session) | | oldSession | string | Yes | Previous anonymous session token |

Request Example:

{
  "session": "authenticated-user-session",
  "oldSession": "anonymous-session-token"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sessionId": "authenticated-user-session",
    "items": [
      {
        "itemId": 0,
        "cartItemId": "client-item-001",
        "productId": 1234,
        "unitId": 5678,
        "unitName": "Desert Safari Premium",
        "description": "Premium Desert Safari with BBQ Dinner",
        "unitPrice": 150.00,
        "quantity": 2.0,
        "child": false,
        "infant": false,
        "bookDate": "2025-06-20T00:00:00",
        "pickupLocation": "Dubai Mall",
        "timeSlot": "15:00-21:00",
        "isAvailable": true,
        "resvName": "John Smith"
      }
    ],
    "paymentRef": null,
    "paymentUrl": null,
    "orderNum": null
  }
}

Error Codes: - MISSING_PARAMETER - Session ID(s) not provided

POST /cart/createInvoice¶

Creates an invoice from the cart contents.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | customer | object | No* | Customer information (for transient carts) | | paid | boolean | No | Whether the invoice is paid online (default: false) |

Customer Object (for transient carts): | Field | Type | Required | Description | |-------|------|----------|-------------| | customerId | integer | No | Existing customer ID (if known) | | email | string | Yes | Customer email address | | custName | string | Yes | Customer full name | | mobilePhone | string | Yes* | Customer mobile phone |

*Required if customerId is not provided.

Request Example (with existing customer):

{
  "session": "user-session-token",
  "customer": {
    "customerId": 12345
  },
  "paid": true
}

Request Example (with new customer):

{
  "session": "user-session-token",
  "customer": {
    "email": "customer@example.com",
    "custName": "John Smith",
    "mobilePhone": "+971501234567"
  },
  "paid": false
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "invoices": ["INV-2025-001234", "INV-2025-001235"]
  }
}

Error Codes: - MISSING_PARAMETER - Session ID or customer info not provided - GENERAL - Cart empty or not found

POST /cart/createPaymentLink¶

Creates a payment link for the cart.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | customer | object | No* | Customer information | | options | object | No | Payment link options |

Customer Object: | Field | Type | Required | Description | |-------|------|----------|-------------| | customerId | integer | No | Existing customer ID | | email | string | Yes | Customer email | | custName | string | Yes | Customer name | | mobilePhone | string | No | Customer mobile phone |

Options Object: | Field | Type | Description | |-------|------|-------------| | host | string | Fully qualified host name of the sending server | | device | string | Screen size: "small", "medium", or "large" |

Request Example:

{
  "session": "user-session-token",
  "customer": {
    "email": "customer@example.com",
    "custName": "John Smith",
    "mobilePhone": "+971501234567"
  },
  "options": {
    "host": "https://www.example.com",
    "device": "large"
  }
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sessionId": "user-session-token",
    "items": [
      {
        "itemId": 0,
        "cartItemId": "client-item-001",
        "productId": 1234,
        "unitId": 5678,
        "unitName": "Desert Safari Premium",
        "description": "Premium Desert Safari with BBQ Dinner",
        "unitPrice": 150.00,
        "quantity": 2.0,
        "bookDate": "2025-06-20T00:00:00",
        "pickupLocation": "Dubai Mall",
        "timeSlot": "15:00-21:00"
      }
    ],
    "paymentRef": "PAY-REF-123456789",
    "paymentUrl": "https://secure.payment-gateway.com/pay/PAY-REF-123456789",
    "orderNum": "SO-2025-001234"
  }
}

Error Codes: - GENERAL - Cart empty or not found

POST /cart/checkPaymentStatus¶

Checks the status of a payment.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | paymentRef | string | Yes | Payment reference to check |

Request Example:

{
  "session": "user-session-token",
  "paymentRef": "PAY-REF-123456789"
}

Response Structure (Successful Payment):

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "method": "check",
    "trace": "TRC-20250615-123456",
    "order": {
      "ref": "PAY-REF-123456789",
      "url": null,
      "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "test": 0,
      "amount": 300.00,
      "currency": "AED",
      "description": "Desert Safari Premium Experience x2",
      "status": {
        "code": 3,
        "text": "Paid"
      },
      "transaction": {
        "ref": "TXN-987654321",
        "class": "sale",
        "status": "A",
        "message": "Authorised",
        "code": "00"
      },
      "paymethod": "card",
      "card": {
        "type": "Visa",
        "last4": "4242",
        "first6": "424242",
        "country": "AE",
        "expiry": {
          "month": 12,
          "year": 2027
        }
      },
      "customer": {
        "email": "customer@example.com",
        "name": {
          "title": "Mr",
          "forenames": "John",
          "surname": "Smith"
        },
        "address": {
          "line1": "123 Main Street",
          "city": "Dubai",
          "country": "AE"
        },
        "ref": "CUST-12345"
      }
    },
    "error": null
  }
}

Response Structure (Pending Payment):

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "method": "check",
    "trace": "TRC-20250615-123456",
    "order": {
      "ref": "PAY-REF-123456789",
      "url": "https://secure.payment-gateway.com/pay/PAY-REF-123456789",
      "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "test": 0,
      "amount": 300.00,
      "currency": "AED",
      "description": "Desert Safari Premium Experience x2",
      "status": {
        "code": 1,
        "text": "Pending"
      },
      "transaction": null,
      "paymethod": null,
      "card": null,
      "customer": null
    },
    "error": null
  }
}

Response Structure (Failed Payment):

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "method": "check",
    "trace": "TRC-20250615-123456",
    "order": {
      "ref": "PAY-REF-123456789",
      "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": 300.00,
      "currency": "AED",
      "status": {
        "code": -3,
        "text": "Declined"
      },
      "transaction": {
        "ref": "TXN-987654321",
        "class": "sale",
        "status": "D",
        "message": "Card declined",
        "code": "05"
      }
    },
    "error": {
      "message": "Payment was declined",
      "note": "Please try a different payment method"
    }
  }
}

Payment Status Codes: | Code | Text | Description | |------|------|-------------| | -3 | Declined | Payment was declined | | -2 | Canceled | Payment was canceled by user | | -1 | Expired | Payment link expired | | 1 | Pending | Payment in progress | | 2 | Authorized | Payment authorized, pending capture | | 3 | Paid | Payment completed successfully |

POST /cart/delete¶

Deletes the cart for the session.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token |

Request Example:

{
  "session": "user-session-token"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": true
}

Data Models¶

CTransientCart¶

Field	Type	Description
cartId	string	Unique cart identifier (UUID)
sessionId	string	Session token associated with cart
items	array	Array of CCartItem objects
paymentRef	string	Payment reference (after payment link created)
paymentUrl	string	Payment URL (after payment link created)
orderNum	string	Associated sales order number

CCartItem¶

Field	Type	Description
itemId	integer	Server-assigned item ID (0-indexed)
cartItemId	string	Client-provided item identifier
productId	integer	Product ID
productTemplateId	integer	Product template ID
unitId	integer	Unit/variant ID
unitName	string	Unit name for display
description	string	Item description
unitPrice	number	Price per unit
quantity	number	Quantity of items
child	boolean	Whether this is a child ticket
infant	boolean	Whether this is an infant ticket
bookDate	datetime	Booking date
extAttr	string	Extended attributes (JSON string)
extVariantId	integer	External variant ID
pickupLocation	string	Pickup location
serviceLocation	string	Service location
xferType	string	Transfer type (SIC, PVT)
timeSlot	string	Selected time slot
startTime	string	Start time
isAvailable	boolean	Whether item is available
ppc	number	Purchase price (cost)
resvName	string	Reservation name

TJTxnResponse¶

Field	Type	Description
method	string	API method called (e.g., "check", "create")
trace	string	Transaction trace ID
order	TJOrderRef	Order/payment details
error	TJErrorInfo	Error details (if any)

TJOrderRef¶

Field	Type	Description
ref	string	Payment reference
url	string	Payment URL
cartId	string	Associated cart ID
test	integer	Test mode flag (0=production, 1=test)
amount	number	Payment amount
currency	string	Currency code (e.g., "AED")
description	string	Payment description
status	TJTxnStatus	Transaction status
transaction	TJTransactionInfo	Transaction details
paymethod	string	Payment method used
card	TJCardInfo	Card details (if card payment)
customer	TJCustomerInfo	Customer details

TJTxnStatus¶

Field	Type	Description
code	integer	Status code (-3 to 3)
text	string	Status text description

TJTransactionInfo¶

Field	Type	Description
ref	string	Transaction reference
class	string	Transaction class (sale, auth, refund)
status	string	Transaction status code
message	string	Status message
code	string	Response code

TJCardInfo¶

Field	Type	Description
type	string	Card type (Visa, Mastercard, etc.)
last4	string	Last 4 digits of card
first6	string	First 6 digits of card (BIN)
country	string	Card issuing country
expiry	object	Card expiry

TJCustomerInfo¶

Field	Type	Description
email	string	Customer email
name	object	Customer name
address	object	Customer address
ref	string	Customer reference

TJErrorInfo¶

Field	Type	Description
message	string	Error message
note	string	Additional error details