Sellers, sites and channels

Sellers

A seller is a local guide or a tour operator: Vacation Packages Oman in Muscat, Dubai Fly Tours in Dubai, Vacations of Africa in Tanzania. A seller owns its trips, prices, calendar and bookings, and runs the trips. Every trip the API returns carries its seller, so a page can always say who runs it.

Sites

A site, which the API calls a storefront, is where trips are sold. Your website key names one. GET /v1/public/storefront says which:

Which site the key belongs to

curl
TypeScript

curl "https://api.stg.vacationpackagesoman.com/v1/public/storefront" \
  -H "Tp-Publishable-Key: $TP_KEY"

const res = await fetch("https://api.stg.vacationpackagesoman.com/v1/public/storefront", {
  headers: {
    "Tp-Publishable-Key": process.env.TP_KEY!,
  },
})
const answer = await res.json()

Answer: 200 OK

{
  "id": "7f3a1d2e-5b6c-4d8e-9f01-2a3b4c5d6e7f",
  "operator_id": "8a4b2e3f-6c7d-4e9f-a012-3b4c5d6e7f80",
  "kind": "direct",
  "name": "tourpingo demo",
  "default_locale": "en",
  "locales": [
    "en",
    "ar"
  ],
  "display_currency": "USD",
  "currencies": [
    "USD",
    "AED"
  ],
  "display_rounding": "up_to_whole",
  "blog_url": null
}

Field	What it is
`kind`	`direct`: one seller’s own site. `marketplace`: tourpingo’s marketplace, selling every seller’s trips approved for it.
`default_locale`, `locales`	The languages the site is in.
`display_currency`, `currencies`	The currency prices are shown in, and the others a traveller can pick.
`display_rounding`	How converted prices are rounded for display: `none`, `up_to_whole` or `up_to_99`.

A seller can have more than one site, each with its own key, languages and currencies.

The same API, one seller or many

On a direct site every trip is the seller’s own. On the marketplace, lists hold many sellers’ trips, and GET /v1/public/sellers lists the sellers:

A marketplace's sellers

curl
TypeScript

curl "https://api.stg.vacationpackagesoman.com/v1/public/sellers?locale=en" \
  -H "Tp-Publishable-Key: $TP_KEY"

const res = await fetch("https://api.stg.vacationpackagesoman.com/v1/public/sellers?locale=en", {
  headers: {
    "Tp-Publishable-Key": process.env.TP_KEY!,
  },
})
const answer = await res.json()

Answer: 200 OK

{
  "data": [
    {
      "slug": "vpo",
      "name": "Vacation Packages Oman",
      "country": {
        "slug": "om",
        "name": "Oman"
      },
      "trip_count": 41,
      "base": "Seeb, Muscat, Oman",
      "blurb": "Day trips and packages across Oman",
      "rating": null
    },
    {
      "slug": "voa",
      "name": "Vacations of Africa",
      "country": {
        "slug": "tz",
        "name": "Tanzania"
      },
      "trip_count": 18,
      "base": "Tanzania",
      "blurb": "Safaris, Zanzibar and Kilimanjaro",
      "rating": null
    },
    {
      "slug": "dft",
      "name": "Dubai Fly Tours",
      "country": {
        "slug": "ae",
        "name": "United Arab Emirates"
      },
      "trip_count": 5,
      "base": "Dubai, UAE",
      "blurb": "Tours in Dubai, Abu Dhabi and Sharjah",
      "rating": null
    }
  ]
}

A marketplace's trips, each with its seller

curl
TypeScript

curl "https://api.stg.vacationpackagesoman.com/v1/public/products?limit=3&locale=en" \
  -H "Tp-Publishable-Key: $TP_KEY"

const res = await fetch("https://api.stg.vacationpackagesoman.com/v1/public/products?limit=3&locale=en", {
  headers: {
    "Tp-Publishable-Key": process.env.TP_KEY!,
  },
})
const answer = await res.json()

Answer: 200 OK (shortened)

{
  "data": [
    {
      "template": "multi_day",
      "content_locale": "en",
      "sales_paused": false,
      "duration_days": 4,
      "duration_nights": 3,
      "id": "0d1e2f3a-4b5c-4d6e-8f70-81a2b3c4d5e6",
      "slug": "zanzibar-the-slave-route",
      "title": "Zanzibar: the slave route",
      "duration_minutes": null,
      "city": {
        "slug": "stone-town",
        "name": "Stone Town"
      },
      "country": {
        "slug": "tz",
        "name": "Tanzania"
      },
      "seller": {
        "slug": "voa",
        "name": "Vacations of Africa"
      },
      "from_price": null
    },
    {
      "template": "day_tour",
      "content_locale": "en",
      "sales_paused": false,
      "duration_days": null,
      "duration_nights": null,
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
      "slug": "desert-safari-with-bbq-dinner",
      "title": "Desert safari with BBQ dinner",
      "duration_minutes": 360,
      "city": {
        "slug": "dubai",
        "name": "Dubai"
      },
      "country": {
        "slug": "ae",
        "name": "United Arab Emirates"
      },
      "seller": {
        "slug": "dft",
        "name": "Dubai Fly Tours"
      },
      "from_price": {
        "amount": 7800,
        "currency": "USD",
        "group_size": 1
      }
    },
    {
      "template": "day_tour",
      "content_locale": "en",
      "sales_paused": false,
      "duration_days": null,
      "duration_nights": null,
      "id": "1e2f3a4b-5c6d-4e7f-9081-92b3c4d5e6f7",
      "slug": "wadi-shab-and-wadi-tiwi",
      "title": "Wadi Shab and Wadi Tiwi",
      "duration_minutes": 480,
      "city": {
        "slug": "muscat",
        "name": "Muscat"
      },
      "country": {
        "slug": "om",
        "name": "Oman"
      },
      "seller": {
        "slug": "vpo",
        "name": "Vacation Packages Oman"
      },
      "from_price": {
        "amount": 9500,
        "currency": "USD",
        "group_size": 4
      }
    }
  ],
  "next_cursor": "WyIyMDI2LTA5LTIwVDA5OjA1OjAwLjAwMFoiLCIxZTJmM2E0Yi01YzZkLTRlN2YtOTA4MS05MmIzYzRkNWU2ZjciXQ",
  "total": 64
}

Two sellers on the marketplace can use the same slug, so open a trip there by its slug with its seller: GET /v1/public/products/{product} with seller, e.g. ?seller=dft. A direct site ignores seller.

Channels

Each booking remembers where it was made, its channel:

direct: on the seller’s own site. The seller collects the money, and tourpingo takes no commission.
marketplace: on tourpingo’s marketplace.

The channel comes from the key, like everything else about the site.