Order Operations
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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

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):

{
  "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

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.

{
  "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

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):

{
  "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

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):

{
  "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

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:

{
  "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

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

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

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.

Order OperationsCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Create Order

Endpoint

Authentication

Request Body

Extra Products

Passenger Information

Billing Address (Optional)

Example Request

Response

Order Status Values

Get Order Details

Endpoint

Authentication

Path Parameters

Example Request

Response

Check Cancel Eligibility

Endpoint

Authentication

Path Parameters

Example Request

Response

Response Fields

Cancel Order

Endpoint

Authentication

Path Parameters

Example Request

Response

Cancel Status Values

Order Creation Workflow

1. Order Initialization

2. Product Addition

3. Passenger Registration

4. Billing Setup

5. Payment Preparation

Order Lifecycle

Order Best Practices

Passenger Information

Billing Address

Extra Products

Error Handling

Validation Rules

Passenger Validation

Credit Type Validation

Billing Validation

Integration Examples

Basic Order Creation

Order with Extra Products

Polling Order Status

Rate Limiting

Was this helpful?

Order Operations
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code