#Endpoints Overview

The Products V2 API provides comprehensive endpoints for managing travel products with enhanced capabilities.

#Base URL

All Products V2 API endpoints are prefixed with /products:

https://api.joinsherpa.io/v2/products

#Authentication

All endpoints require API key authentication with appropriate permissions:

• Required Roles: Admin or Editor
• Required Scope: Products
• Header: x-api-key: YOUR_API_KEY_HERE

#Common Headers

All requests should include:

Content-Type: application/json
x-api-key: YOUR_API_KEY_HERE

All responses include:

Content-Type: application/json
Cache-Control: public, max-age=3600
Vary: origin, x-affiliate-id, x-api-key

#Endpoint Categories

#Product Management

#Product Migration

#Common Query Parameters

Many endpoints support these query parameters:

#Filtering Parameters

• status - Filter by product status (ACTIVE, INACTIVE, ALL)
• provider - Filter by provider (default: SHERPA)
• destination - Filter by destination country (ISO 3-letter code)
• nationality - Filter by nationality (ISO 3-letter code)
• subType - Filter by EER type (E_VISA, ETA, E_TOURIST_CARD, PAPER_VISA)
• travelPurpose - Filter by travel purpose

#Localization Parameters

• currency - Currency for pricing (default: USD)
• language - Language for localization (default: en-US)

#Advanced Parameters

• consolidateProducts - Consolidate product variants (default: false)
• arrivalDate - Arrival date (not implemented yet)
• residenceCountry - Residence country (not implemented yet)

#Error Responses

All endpoints can return standard error responses:

{
  "errorCode": "ERROR_CODE",
  "message": "Human-readable error message",
  "data": {
    "additional": "error details"
  }
}

Common HTTP status codes:

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 204 No Content - Request successful, no content returned
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server-side error

#Data Types

#Product Status

enum ProductStatus {
  ACTIVE = "ACTIVE"
  INACTIVE = "INACTIVE"
}

#EER Types

enum EerType {
  E_VISA = "E_VISA"
  ETA = "ETA"
  E_TOURIST_CARD = "E_TOURIST_CARD"
  PAPER_VISA = "PAPER_VISA"
}

#Travel Purpose Types

enum ProductTravelPurposeType {
  Tourism = "TOURISM"
  BusinessVisitor = "BUSINESS_VISITOR"
  Transit = "TRANSIT"
  Medical = "MEDICAL"
  MedicalAttendant = "MEDICAL_ATTENDANT"
  Conference = "CONFERENCE"
  Business = "BUSINESS"
  ShortTermStudy = "SHORT_TERM_STUDY"
}

#Number of Entries

enum NumberOfEntriesType {
  SINGLE = "SINGLE"
  MULTIPLE = "MULTIPLE"
  DOUBLE = "DOUBLE"
}

#Price Breakdown Types

enum PriceBreakdownType {
  GOVERNMENT_FEE = "GOVERNMENT_FEE"
  GOVERNMENT_PROCESSING_FEE = "GOVERNMENT_PROCESSING_FEE"
  APPLICATION_SERVICE_FEE = "APPLICATION_SERVICE_FEE"
  INTERNATIONAL_VISITOR_LEVY = "INTERNATIONAL_VISITOR_LEVY"
  PRIORITY_PROCESSING = "PRIORITY_PROCESSING"
  APPLICATION_SERVICE_FEE_DISCOUNT = "APPLICATION_SERVICE_FEE_DISCOUNT"
}

#Best Practices

#Request Optimization

• Use specific query parameters to filter results
• Implement pagination for large datasets
• Cache responses according to cache headers
• Use partial updates (PATCH) instead of full updates (PUT) when possible

#Error Handling

• Always check HTTP status codes
• Parse error responses for detailed error information
• Implement retry logic with exponential backoff
• Log errors for debugging and monitoring

#Security

• Store API keys securely
• Use HTTPS for all API communications
• Rotate API keys regularly
• Never expose API keys in client-side code

#Performance

• Follow the 1-hour cache duration for optimal performance
• Use appropriate query parameters to reduce response size
• Implement client-side caching for frequently accessed data
• Monitor rate limits and implement appropriate throttling