# Order Operations

Order endpoints allow you to create and manage car rental reservations. The order system handles the complete booking
workflow including vehicle selection, passenger information, billing details, and integration with payment processing.

## Create Order

Creates a new car rental order. This endpoint initiates the comprehensive booking process including vehicle reservation,
passenger registration, and payment preparation.

### Endpoint


```
POST /order
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header:


```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Request Body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `paymentType` | string | Yes | Payment method: `creditCard` or `limit` |
| `searchID` | string | Yes | Search ID obtained from vehicle search results |
| `code` | string | Yes | Selected vehicle product code from search results |
| `extraProducts` | array | No | List of additional products and services |
| `passenger` | object | Yes | Primary passenger information |
| `billing` | object | No | Custom billing address (optional, defaults to passenger info) |
| `isFullCredit` | boolean | No | Use full credit payment (agency must be authorized) |
| `isLimitedCredit` | boolean | No | Use limited credit payment (agency must be authorized) |


#### Extra Products

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `code` | string | Yes | Product code from extra products search |
| `quantity` | integer | Yes | Quantity to add (minimum 1) |


#### Passenger Information

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `firstName` | string | Yes | Passenger first name |
| `lastName` | string | Yes | Passenger last name |
| `email` | string | Yes | Valid email address |
| `nationality` | string | Yes | ISO country code (2 characters) |
| `phone` | string | Yes | Phone number in E.164 format |
| `birthDate` | string | Yes | Birth date (YYYY-MM-DD format) |
| `identityNumber` | string | No | 11-digit identity number (for Turkish citizens) |
| `passportNo` | string | No | Passport number (for international travelers) |


#### Billing Address (Optional)

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `type` | string | Yes | Address type: `individual` or `corporateCompany` |
| `label` | string | No | Custom label for the address |
| `firstName` | string | Yes | Billing first name |
| `lastName` | string | No | Billing last name |
| `email` | string | No | Billing email address |
| `phone` | string | No | Billing phone number |
| `countryName` | string | Yes | Full country name |
| `countryCode` | string | Yes | ISO country code (2 characters) |
| `adm1` | string | Yes | Administrative division level 1 (state/province) |
| `adm2` | string | No | Administrative division level 2 (city/district) |
| `line` | string | No | Address line (street address) |
| `zipCode` | string | No | Postal/ZIP code |
| `taxDivision` | string | No | Tax office/division |
| `taxIdentifier` | string | No | Tax ID number |


### Example Request


```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/order \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "paymentType": "creditCard",
    "searchID": "search_123456789",
    "code": "ECAR",
    "isFullCredit": true,
    "isLimitedCredit": false,
    "extraProducts": [
      {
        "code": "GPS",
        "quantity": 1
      },
      {
        "code": "CDW",
        "quantity": 1
      }
    ],
    "passenger": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "nationality": "US",
      "phone": "+1234567890",
      "birthDate": "1990-01-15",
      "passportNo": "ABC123456"
    },
    "billing": {
      "type": "individual",
      "label": "Home Address",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "countryName": "United States",
      "countryCode": "US",
      "adm1": "California",
      "adm2": "Los Angeles",
      "line": "123 Main Street",
      "zipCode": "90210"
    }
  }'
```

### Response

**Success Response (201 Created):**


```json
{
  "id": "order_123456789",
  "paymentType": "creditCard",
  "paymentCurrency": "TRY",
  "language": "en",
  "createdAt": "2024-12-25T10:00:00Z",
  "updatedAt": "2024-12-25T10:00:00Z",
  "passenger": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "nationality": "US",
    "phone": "+1234567890"
  },
  "billing": {
    "type": "individual",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  },
  "orderedCarProduct": {
    "id": 1001,
    "status": "pending",
    "quantity": 1,
    "isFullCredit": true,
    "isLimitedCredit": false,
    "vendorCancelled": false,
    "createdAt": "2024-12-25T10:00:00Z",
    "updatedAt": "2024-12-25T10:00:00Z",
    "car": {
      "code": "ECAR",
      "searchID": "search_123456789",
      "brand": {
        "id": "toyota",
        "name": "Toyota"
      },
      "model": {
        "id": "corolla",
        "name": "Corolla"
      },
      "class": {
        "id": "economy",
        "name": "Economy"
      },
      "imageURL": "https://example.com/car-image.jpg",
      "pricing": {
        "total": {
          "amount": 50000,
          "currency": "TRY"
        },
        "paymentTotal": {
          "amount": 50000,
          "currency": "TRY"
        }
      }
    }
  },
  "orderedExtraProducts": [
    {
      "id": 1002,
      "status": "pending",
      "quantity": 1,
      "vendorCancelled": false,
      "createdAt": "2024-12-25T10:00:00Z",
      "updatedAt": "2024-12-25T10:00:00Z",
      "extraProduct": {
        "code": "GPS",
        "name": "GPS Navigation System",
        "type": "equipment",
        "pricing": {
          "total": {
            "amount": 1500,
            "currency": "TRY"
          }
        }
      }
    },
    {
      "id": 1003,
      "status": "pending",
      "quantity": 1,
      "vendorCancelled": false,
      "createdAt": "2024-12-25T10:00:00Z",
      "updatedAt": "2024-12-25T10:00:00Z",
      "extraProduct": {
        "code": "CDW",
        "name": "Collision Damage Waiver",
        "type": "insurance",
        "pricing": {
          "total": {
            "amount": 3000,
            "currency": "TRY"
          }
        }
      }
    }
  ]
}
```

### Order Status Values

| Status | Description |
|  --- | --- |
| `pending` | Item added to order, awaiting confirmation |
| `reserved` | Item successfully reserved with vendor |
| `failed` | Item reservation failed |
| `cancelled` | Item cancelled by user or vendor |
| `removed` | Item removed from order |


## Get Order Details

Retrieve comprehensive details of a specific order including current status, passenger information, ordered products,
and payment information.

### Endpoint


```
GET /order/{orderID}
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Path Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `orderID` | string | Yes | Unique order identifier |


### Example Request


```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/order/order_123456789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**

Returns the same structure as the create order response, with updated status information and any changes that have
occurred since creation.


```json
{
  "id": "order_123456789",
  "paymentType": "creditCard",
  "paymentCurrency": "TRY",
  "language": "en",
  "createdAt": "2024-12-25T10:00:00Z",
  "updatedAt": "2024-12-25T10:15:00Z",
  "passenger": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "nationality": "US",
    "phone": "+1234567890"
  },
  "orderedCarProduct": {
    "id": 1001,
    "status": "reserved",
    "quantity": 1,
    "isFullCredit": false,
    "vendorCancelled": false,
    "vendorReservationID": "AVIS_RES_789012",
    "paymentID": 2001,
    "createdAt": "2024-12-25T10:00:00Z",
    "updatedAt": "2024-12-25T10:15:00Z",
    "car": {
      "code": "ECAR",
      "searchID": "search_123456789",
      "brand": {
        "id": "toyota",
        "name": "Toyota"
      },
      "model": {
        "id": "corolla",
        "name": "Corolla"
      }
    }
  },
  "orderedExtraProducts": [
    {
      "id": 1002,
      "status": "reserved",
      "quantity": 1,
      "paymentID": 2001,
      "vendorReservationID": "AVIS_GPS_789013"
    }
  ]
}
```

## Check Cancel Eligibility

Checks whether an order is eligible for cancellation and refund. This endpoint does not modify the order but provides
information about the cancellation and refund eligibility status.

### Endpoint


```
POST /order/{orderID}/cancel_eligibility
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Path Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `orderID` | string | Yes | Unique identifier of order to check |


### Example Request


```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/order/YLP_123456/cancel_eligibility \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
{
  "cancellable": true,
  "refundable": true
}
```

### Response Fields

| Field | Type | Description |
|  --- | --- | --- |
| `cancellable` | boolean | Whether the order is eligible for cancellation |
| `refundable` | boolean | Whether the order is eligible for refund if cancelled |


## Cancel Order

Cancels an existing order. The order must be in a cancellable state for this operation to succeed. This endpoint will
attempt to cancel the order with the vendor and update the order status accordingly.

### Endpoint


```
POST /order/{orderID}/cancel
```

### Authentication

This endpoint requires authentication. Include your JWT access token in the Authorization header.

### Path Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `orderID` | string | Yes | Unique identifier of order to cancel |


### Example Request


```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/order/YLP_123456/cancel \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response

**Success Response (200 OK):**


```json
{
  "success": true,
  "message": "Order has been successfully cancelled",
  "orderId": "YLP_123456",
  "status": "success"
}
```

### Cancel Status Values

| Status | Description |
|  --- | --- |
| `pending` | Cancellation request is being processed |
| `success` | Order was successfully cancelled |
| `failed` | Cancellation request failed |


## Order Creation Workflow

The order creation process involves multiple steps executed automatically by the system:

### 1. Order Initialization

- Creates base order record
- Validates search session and vehicle availability
- Sets initial status to "open"


### 2. Product Addition

- Adds selected vehicle to the order
- Adds any selected extra products
- Calculates total pricing including commissions


### 3. Passenger Registration

- Validates passenger information
- Stores passenger details securely
- Links passenger to the order


### 4. Billing Setup

- Uses custom billing address if provided
- Falls back to passenger information for billing
- Validates billing information completeness


### 5. Payment Preparation

- Calculates final payment amounts
- Determines payment requirements based on payment type
- Prepares order for payment processing


### Order Lifecycle


```mermaid
graph TD
    A[Create Order] --> B[Add Vehicle]
    B --> C[Add Extra Products]
    C --> D[Add Passenger Info]
    D --> E[Add Billing Info]
    E --> F[Calculate Totals]
    F --> G[Order Ready for Payment]
    G --> H[Process Payment]
    H --> I{Payment Success?}
    I -->|Yes| J[Reserve with Vendor]
    I -->|No| K[Payment Failed]
    J --> L[Order Complete]
    K --> M[Retry Payment]
    M --> H
```

## Order Best Practices

### Passenger Information

- **Required Fields**: Ensure all mandatory passenger fields are provided
- **Document Validation**: Provide either identity number (for domestic) or passport (for international)
- **Contact Information**: Use valid email and phone number for notifications
- **Age Verification**: Ensure passenger meets minimum age requirements


### Billing Address

- **Optional Usage**: Only provide billing address if different from passenger address
- **Corporate Orders**: Use company billing information for business rentals
- **Tax Information**: Include tax details for corporate billing addresses
- **Address Validation**: Ensure address information is complete and accurate


### Extra Products

- **Quantity Limits**: Respect minimum and maximum quantity constraints
- **Compatibility**: Verify product compatibility with selected vehicle
- **Pricing Updates**: Extra product prices may change between search and order


### Error Handling

**Common Error Responses:**

- `400 Bad Request`: Invalid order data or missing required fields
- `401 Unauthorized`: Authentication required or token expired
- `404 Not Found`: Search session expired or vehicle unavailable
- `422 Unprocessable Entity`: Validation errors in passenger or billing data
- `500 Internal Server Error`: System error during order processing


**Example Error Response:**


```json
{
  "code": 1001,
  "description": "Invalid passenger information",
  "details": {
    "field": "passenger.email",
    "message": "Invalid email format"
  }
}
```

### Validation Rules

#### Passenger Validation

- **Email**: Must be valid email format
- **Phone**: Must be in E.164 international format
- **Birth Date**: Must be valid date and meet minimum age requirements
- **Nationality**: Must be valid ISO country code
- **Identity/Passport**: Required based on nationality and travel requirements


#### Credit Type Validation

- **Mutual Exclusivity**: Only one of `isFullCredit` or `isLimitedCredit` can be `true`
- **Agency Authorization**: Agency must be configured to use the selected credit type


#### Billing Validation

- **Type**: Must be one of: individual, corporateCompany
- **Country**: Country code must match country name
- **Corporate Fields**: Tax division and identifier required for company types
- **Address**: Administrative divisions must be valid for the country


## Integration Examples

### Basic Order Creation


```javascript
async function createOrder(searchResult, passengerInfo) {
    const orderData = {
        paymentType: 'creditCard',
        searchID: searchResult.searchID,
        code: searchResult.code,
        passenger: {
            firstName: passengerInfo.firstName,
            lastName: passengerInfo.lastName,
            email: passengerInfo.email,
            nationality: passengerInfo.nationality,
            phone: passengerInfo.phone,
            birthDate: passengerInfo.birthDate
        }
    };

    const response = await fetch('/api/v1/order', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify(orderData)
    });

    if (!response.ok) {
        const error = await response.json();
        throw new Error(`Order creation failed: ${error.description}`);
    }

    return await response.json();
}
```

### Order with Extra Products


```javascript
async function createOrderWithExtras(searchResult, passengerInfo, selectedExtras) {
    const orderData = {
        paymentType: 'creditCard',
        searchID: searchResult.searchID,
        code: searchResult.code,
        extraProducts: selectedExtras.map(extra => ({
            code: extra.code,
            quantity: extra.quantity
        })),
        passenger: passengerInfo
    };

    return await createOrder(orderData);
}
```

### Polling Order Status


```javascript
async function waitForOrderCompletion(orderID, maxWaitTime = 300000) {
    const startTime = Date.now();

    while (Date.now() - startTime < maxWaitTime) {
        const order = await getOrder(orderID);

        if (order.status === 'closed') {
            return order;
        }

        if (order.orderedCarProduct.status === 'failed') {
            throw new Error('Order failed - vehicle reservation unsuccessful');
        }

        // Wait 5 seconds before checking again
        await new Promise(resolve => setTimeout(resolve, 5000));
    }

    throw new Error('Order completion timeout');
}
```

## Rate Limiting

Order endpoints are subject to rate limiting:

- **Create order**: Maximum 5 requests per minute per user
- **Get order**: Maximum 60 requests per minute per user


Monitor rate limit headers in responses and implement appropriate retry logic.