Overview
Get API access
API
Overview
Get API access
API

Get Product by ID

GET /products/{productId}

Retrieves a specific product by its ID with localization and pricing information.

Request

Headers

x-api-key: YOUR_API_KEY_HERE

Path Parameters

  • productId (string, required): The unique identifier of the product

Query Parameters

Query
{
  currency?: string                        // Currency for pricing (default: "USD")
  language?: string                        // Language for localization (default: "en-US")
}

Example Requests

Get Product with Default Currency

Get
curl --location 'https://api.joinsherpa.io/v2/products/turkey-evisa-tourism' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Get Product with Specific Currency

Get
curl --location 'https://api.joinsherpa.io/v2/products/turkey-evisa-tourism?currency=EUR' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Get Product with Localization

Get
curl --location 'https://api.joinsherpa.io/v2/products/turkey-evisa-tourism?language=fr-FR&currency=EUR' \
--header 'x-api-key: YOUR_API_KEY_HERE'

Response

Success Response (200 OK)

Product
{
  "name": "Turkey eVisa",
  "shortName": "Turkey eVisa",
  "imageUrl": "https://example.com/turkey-evisa.jpg",
  "shortDescription": "Electronic visa for Turkey",
  "description": "Electronic visa for Turkey tourism and business travel. Fast processing and easy application process.",
  "displayOrder": 1,
  "programId": "turkey-evisa",
  "productId": "turkey-evisa-tourism",
  "status": "ACTIVE",
  "hasVariants": false,
  "isVariant": false,
  "type": "visa",
  "subType": {
    "value": "E_VISA",
    "label": "Electronic Visa"
  },
  "provider": {
    "value": "SHERPA",
    "label": "Sherpa"
  },
  "valuePropositions": [
    {
      "title": "Fast Processing",
      "description": "Get your visa approved in as little as 24 hours"
    },
    {
      "title": "Easy Application",
      "description": "Simple online application process with step-by-step guidance"
    },
    {
      "title": "Secure & Reliable",
      "description": "Government-approved process with secure data handling"
    }
  ],
  "numberOfEntries": {
    "value": "SINGLE",
    "label": "Single Entry"
  },
  "actions": [
    {
      "type": "LINK",
      "title": "Apply Now",
      "description": "Start your Turkey eVisa application",
      "url": "https://sherpa-widget.joinsherpa.io/applications/products/turkey-evisa-tourism"
    }
  ],
  "lengthOfStay": {
    "value": 90,
    "unit": "DAYS",
    "label": "90 days"
  },
  "validity": {
    "value": 180,
    "unit": "DAYS",
    "startsFrom": "APPROVAL",
    "label": "180 days from approval"
  },
  "processingTime": {
    "value": 24,
    "unit": "HOURS",
    "label": "24 hours"
  },
  "processingWindow": {
    "value": 72,
    "unit": "HOURS",
    "label": "72 hours"
  },
  "earliestApplyDate": {
    "value": 30,
    "unit": "DAYS",
    "label": "30 days before travel"
  },
  "applicationDeadline": {
    "value": 24,
    "unit": "HOURS",
    "label": "24 hours before travel"
  },
  "travelPurposes": [
    {
      "value": "TOURISM",
      "label": "Tourism"
    },
    {
      "value": "BUSINESS_VISITOR",
      "label": "Business Visitor"
    }
  ],
  "destinations": [
    {
      "value": "TUR",
      "label": "Turkey"
    }
  ],
  "eligibleNationalities": [
    {
      "value": "USA",
      "label": "United States"
    },
    {
      "value": "CAN",
      "label": "Canada"
    },
    {
      "value": "GBR",
      "label": "United Kingdom"
    }
  ],
  "startDate": "2024-01-01",
  "prerequisites": [
    {
      "title": "Valid Passport",
      "description": "Passport must be valid for at least 6 months from entry date",
      "type": "REQUIRED",
      "value": {
        "type": "PASSPORT_VALIDITY",
        "duration": {
          "value": 6,
          "unit": "MONTHS"
        }
      }
    },
    {
      "title": "Return Ticket",
      "description": "Proof of return or onward travel",
      "type": "REQUIRED",
      "value": {
        "type": "RETURN_TICKET"
      }
    }
  ],
  "pricing": {
    "price": 75.00,
    "currency": "USD",
    "breakdown": [
      {
        "type": "GOVERNMENT_FEE",
        "price": 50.00,
        "label": "Government Fee"
      },
      {
        "type": "APPLICATION_SERVICE_FEE",
        "price": 25.00,
        "label": "Application Service Fee"
      }
    ]
  },
  "notices": [
    {
      "title": "Important Notice",
      "description": "Passport must be valid for at least 6 months from entry date",
      "type": "WARNING"
    },
    {
      "title": "Processing Time",
      "description": "Processing time may vary during peak travel seasons",
      "type": "INFO"
    }
  ],
  "excludedAffiliateIds": [],
  "includedAffiliateIds": []
}

JavaScript Example

Get
const getProductById = async (productId, options = {}) => {
  try {
    // Build query parameters
    const params = new URLSearchParams();
    if (options.currency) params.append('currency', options.currency);
    if (options.language) params.append('language', options.language);

    const url = `https://api.joinsherpa.io/v2/products/${productId}?${params}`;
    
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'x-api-key': `${API_KEY}`,
      },
    });

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Product with ID '${productId}' not found`);
      }
      const errorData = await response.json();
      throw new Error(`API Error: ${errorData.message}`);
    }

    const product = await response.json();
    console.log('Product retrieved:', product);
    return product;
  } catch (error) {
    console.error('Error retrieving product:', error);
    throw error;
  }
};

// Usage examples
const examples = {
  // Get product with default settings
  getProduct: (productId) => getProductById(productId),
  
  // Get product with EUR currency
  getProductInEUR: (productId) => getProductById(productId, { 
    currency: 'EUR' 
  }),
  
  // Get product with French localization
  getProductInFrench: (productId) => getProductById(productId, { 
    language: 'fr-FR',
    currency: 'EUR' 
  }),
  
  // Get product with multiple options
  getProductWithOptions: (productId) => getProductById(productId, { 
    currency: 'GBP',
    language: 'en-GB' 
  })
};

// Example usage
examples.getProduct('turkey-evisa-tourism').then(product => {
  console.log('Product details:', product);
  console.log('Product name:', product.name);
  console.log('Price:', product.pricing.price, product.pricing.currency);
  console.log('Processing time:', product.processingTime.label);
});

Localization Support

The API supports localization for product information:

Supported Languages

  • en-US - English (US) - Default
  • en-GB - English (UK)
  • fr-FR - French (France)
  • de-DE - German (Germany)
  • es-ES - Spanish (Spain)
  • it-IT - Italian (Italy)
  • pt-BR - Portuguese (Brazil)
  • ja-JP - Japanese (Japan)
  • ko-KR - Korean (South Korea)
  • zh-CN - Chinese (Simplified)

Localized Fields

When a language is specified, the following fields are localized:

  • name - Product name
  • shortName - Short display name
  • description - Product description
  • shortDescription - Brief description
  • valuePropositions - Value proposition titles and descriptions
  • notices - Notice titles and descriptions
  • prerequisites - Prerequisite titles and descriptions

Currency Support

The API supports multiple currencies with real-time conversion:

Supported Currencies

  • USD - US Dollar (Default)
  • EUR - Euro
  • GBP - British Pound
  • CAD - Canadian Dollar
  • AUD - Australian Dollar
  • JPY - Japanese Yen
  • CHF - Swiss Franc
  • SEK - Swedish Krona
  • NOK - Norwegian Krone
  • DKK - Danish Krone

Currency Conversion

  • Prices are automatically converted using current exchange rates
  • Conversion is applied to all price breakdown items
  • Currency is specified in the response pricing.currency field

Error Responses

404 Not Found

{
  "errorCode": "PRODUCT_NOT_FOUND",
  "message": "Product not found",
  "data": {
    "productId": "non-existent-product-id"
  }
}

400 Bad Request

{
  "errorCode": "INVALID_PARAMETERS",
  "message": "Invalid query parameters",
  "data": {
    "field": "currency",
    "reason": "Unsupported currency code"
  }
}

401 Unauthorized

{
  "errorCode": "UNAUTHORIZED",
  "message": "Missing or invalid authentication token"
}

403 Forbidden

{
  "errorCode": "INSUFFICIENT_PERMISSIONS",
  "message": "User does not have required permissions to view this product"
}

Best Practices

Product ID Management

  • Use descriptive, unique product IDs
  • Follow consistent naming conventions
  • Avoid special characters in product IDs
  • Use kebab-case for better readability

Localization Strategy

  • Always specify the target language for international applications
  • Use appropriate currency for the target market
  • Test localized content for accuracy
  • Fall back to default language if localization fails

Caching Strategy

  • Cache product details for 1 hour (as per cache headers)
  • Implement cache invalidation on product updates
  • Use conditional requests for efficient data synchronization
  • Consider user-specific caching for personalized content

Error Handling

  • Handle 404 errors gracefully for missing products
  • Implement retry logic for transient errors
  • Provide meaningful error messages to users
  • Log errors for debugging and monitoring
💡 Performance Tip

For applications displaying multiple products, consider using the GET /products endpoint with filtering instead of making multiple individual requests to this endpoint.