Partner API reference

Version 1.0.0 · REST + JSON · webhooks

Overview

Book professional local photoshoots for your guests in destinations around the world.

Authentication: send your API key as Authorization: Bearer <key>. Keys starting with sk_test_ work in test mode: bookings are not sent to photographers, are never invoiced and their status can be simulated with POST /bookings/{id}/simulate.

Times are always local wall-clock time at the shoot location (YYYY-MM-DDTHH:MM).

Idempotency: send an Idempotency-Key header with POST /bookings. Repeating the request with the same key returns the original response instead of creating a second booking.

Webhooks: we POST events to your webhook URL, signed with Smiler-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Respond with any 2xx status. Failed deliveries are retried for up to 2 days, so an event can arrive late or more than once: use the Smiler-Delivery id to ignore duplicates and booking.updated_at to keep the newest state.

Base URL: https://app-api.smiler.co/api/partner/v1

Errors: non-2xx responses return {"error": {"code", "message", "details"}}.

Rate limit: 120 requests per minute per API key.

Getting a key: contact us — you receive a test key first.

Account

GET/me

Your partner account and terms

Request

curl "https://app-api.smiler.co/api/partner/v1/me" \
  -H "Authorization: Bearer sk_test_…"

Response 200

{
  "partner": "Imagine Cruising",
  "mode": "test",
  "pricing_mode": "our_prices",
  "commission_pct": 20,
  "currency": "EUR",
  "free_cancellation_hours": 48,
  "min_notice_hours": 72,
  "guest_emails": true
}

401 Missing or invalid API key

Catalogue

GET/products

Bookable photoshoot packages with your net price

Parameter	In	Type	Description
country	query	string	ISO 3166-1 alpha-2 country code
city	query	string	City slug

Request

curl "https://app-api.smiler.co/api/partner/v1/products" \
  -H "Authorization: Bearer sk_test_…"

Response 200

{
  "data": [
    {
      "id": 1234,
      "name": "Photoshoot in Paris",
      "city": {
        "name": "Paris",
        "slug": "paris"
      },
      "country_code": "FR",
      "timezone": "Europe/Paris",
      "tier": "premium",
      "duration_minutes": 60,
      "photos_included": 30,
      "meeting_point": "Trocadéro fountains",
      "retail_price": 229,
      "commission_pct": 20,
      "net_price": 183.2,
      "currency": "EUR"
    }
  ]
}

GET/coverage

Check photographer availability for a city and date

Parameter	In	Type
city*	query	string
date*	query	string
time	query	string

Request

curl "https://app-api.smiler.co/api/partner/v1/coverage" \
  -H "Authorization: Bearer sk_test_…"

Response 200

{
  "city": "Paris",
  "date": "2026-11-03",
  "time": "10:00",
  "photographers_available": 6,
  "available": true
}

404 Unknown city

Bookings

GET/bookings

List your bookings (newest first)

Parameter	In	Type
status	query	Status
updated_since	query	string
limit	query	integer
cursor	query	string

Request

curl "https://app-api.smiler.co/api/partner/v1/bookings" \
  -H "Authorization: Bearer sk_test_…"

Response 200

{
  "data": [
    {
      "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
      "reference": "KD4BQHZR",
      "partner_reference": "IC-48213",
      "mode": "live",
      "status": "received",
      "product": {
        "id": 1234,
        "name": "Photoshoot in Paris",
        "duration_minutes": 60,
        "photos_included": 30
      },
      "city": "Paris",
      "country_code": "FR",
      "timezone": "Europe/Paris",
      "start_local": "2026-11-03T10:00",
      "end_local": "2026-11-03T11:00",
      "start_utc": "2026-11-03T09:00:00.000Z",
      "latest_end_local": "2026-11-03T13:30",
      "ship_name": "Sky Princess",
      "port": "Le Havre",
      "meeting_point": "Trocadéro fountains",
      "notes": "Anniversary",
      "guest": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+44 7700 900123",
        "group_size": 2
      },
      "photographer": {
        "first_name": "Camille"
      },
      "guest_page_url": "https://smiler.co/b/KD4BQHZR",
      "gallery": {
        "url": "https://smiler.co/gallery/ab12cd34",
        "delivered_at": "2026-11-05T16:20:00.000Z"
      },
      "price": {
        "currency": "EUR",
        "retail": 229,
        "commission_pct": 20,
        "commission": 45.8,
        "net": 183.2
      },
      "cancellation": {
        "free_until": "2026-11-01T09:00:00.000Z",
        "cancelled_at": null,
        "reason": null,
        "charged": null
      },
      "created_at": "2026-10-07T14:55:00.000Z",
      "updated_at": "2026-10-08T09:12:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

POST/bookings

Create a booking

Parameter	In	Type	Description
Idempotency-Key	header	string

Request

curl -X POST "https://app-api.smiler.co/api/partner/v1/bookings" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_reference": "IC-48213",
    "product_id": 1234,
    "start_local": "2026-11-03T10:00",
    "latest_end_local": "2026-11-03T13:30",
    "guest": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+44 7700 900123"
    },
    "group_size": 2,
    "meeting_point": "Trocadéro fountains",
    "notes": "Anniversary, would love sunset light",
    "ship_name": "Sky Princess",
    "port": "Le Havre"
  }'

Response 201

{
  "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
  "reference": "KD4BQHZR",
  "partner_reference": "IC-48213",
  "mode": "live",
  "status": "received",
  "product": {
    "id": 1234,
    "name": "Photoshoot in Paris",
    "duration_minutes": 60,
    "photos_included": 30
  },
  "city": "Paris",
  "country_code": "FR",
  "timezone": "Europe/Paris",
  "start_local": "2026-11-03T10:00",
  "end_local": "2026-11-03T11:00",
  "start_utc": "2026-11-03T09:00:00.000Z",
  "latest_end_local": "2026-11-03T13:30",
  "ship_name": "Sky Princess",
  "port": "Le Havre",
  "meeting_point": "Trocadéro fountains",
  "notes": "Anniversary",
  "guest": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "group_size": 2
  },
  "photographer": {
    "first_name": "Camille"
  },
  "guest_page_url": "https://smiler.co/b/KD4BQHZR",
  "gallery": {
    "url": "https://smiler.co/gallery/ab12cd34",
    "delivered_at": "2026-11-05T16:20:00.000Z"
  },
  "price": {
    "currency": "EUR",
    "retail": 229,
    "commission_pct": 20,
    "commission": 45.8,
    "net": 183.2
  },
  "cancellation": {
    "free_until": "2026-11-01T09:00:00.000Z",
    "cancelled_at": null,
    "reason": null,
    "charged": null
  },
  "created_at": "2026-10-07T14:55:00.000Z",
  "updated_at": "2026-10-08T09:12:00.000Z"
}

404 Product not found
409 Duplicate partner_reference or Idempotency-Key in progress
422 Validation error, too short notice or the shoot does not fit the time window

GET/bookings/{id}

Get a booking

Parameter	In	Type	Description
id*	path	string	Smiler booking id or your partner_reference

Request

curl "https://app-api.smiler.co/api/partner/v1/bookings/IC-48213" \
  -H "Authorization: Bearer sk_test_…"

Response 200

{
  "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
  "reference": "KD4BQHZR",
  "partner_reference": "IC-48213",
  "mode": "live",
  "status": "received",
  "product": {
    "id": 1234,
    "name": "Photoshoot in Paris",
    "duration_minutes": 60,
    "photos_included": 30
  },
  "city": "Paris",
  "country_code": "FR",
  "timezone": "Europe/Paris",
  "start_local": "2026-11-03T10:00",
  "end_local": "2026-11-03T11:00",
  "start_utc": "2026-11-03T09:00:00.000Z",
  "latest_end_local": "2026-11-03T13:30",
  "ship_name": "Sky Princess",
  "port": "Le Havre",
  "meeting_point": "Trocadéro fountains",
  "notes": "Anniversary",
  "guest": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "group_size": 2
  },
  "photographer": {
    "first_name": "Camille"
  },
  "guest_page_url": "https://smiler.co/b/KD4BQHZR",
  "gallery": {
    "url": "https://smiler.co/gallery/ab12cd34",
    "delivered_at": "2026-11-05T16:20:00.000Z"
  },
  "price": {
    "currency": "EUR",
    "retail": 229,
    "commission_pct": 20,
    "commission": 45.8,
    "net": 183.2
  },
  "cancellation": {
    "free_until": "2026-11-01T09:00:00.000Z",
    "cancelled_at": null,
    "reason": null,
    "charged": null
  },
  "created_at": "2026-10-07T14:55:00.000Z",
  "updated_at": "2026-10-08T09:12:00.000Z"
}

404 Not found

PATCH/bookings/{id}

Update guest details, notes or reschedule

Date and time can be changed until the free cancellation deadline. All other fields can be changed until the shoot.

Parameter	In	Type	Description
id*	path	string	Smiler booking id or your partner_reference

Request

curl -X PATCH "https://app-api.smiler.co/api/partner/v1/bookings/IC-48213" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "start_local": "string",
    "latest_end_local": "string",
    "guest": {
      "name": "string",
      "email": "string",
      "phone": "string"
    },
    "group_size": 1,
    "meeting_point": "string",
    "notes": "string",
    "ship_name": "string",
    "port": "string"
  }'

Response 200

{
  "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
  "reference": "KD4BQHZR",
  "partner_reference": "IC-48213",
  "mode": "live",
  "status": "received",
  "product": {
    "id": 1234,
    "name": "Photoshoot in Paris",
    "duration_minutes": 60,
    "photos_included": 30
  },
  "city": "Paris",
  "country_code": "FR",
  "timezone": "Europe/Paris",
  "start_local": "2026-11-03T10:00",
  "end_local": "2026-11-03T11:00",
  "start_utc": "2026-11-03T09:00:00.000Z",
  "latest_end_local": "2026-11-03T13:30",
  "ship_name": "Sky Princess",
  "port": "Le Havre",
  "meeting_point": "Trocadéro fountains",
  "notes": "Anniversary",
  "guest": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "group_size": 2
  },
  "photographer": {
    "first_name": "Camille"
  },
  "guest_page_url": "https://smiler.co/b/KD4BQHZR",
  "gallery": {
    "url": "https://smiler.co/gallery/ab12cd34",
    "delivered_at": "2026-11-05T16:20:00.000Z"
  },
  "price": {
    "currency": "EUR",
    "retail": 229,
    "commission_pct": 20,
    "commission": 45.8,
    "net": 183.2
  },
  "cancellation": {
    "free_until": "2026-11-01T09:00:00.000Z",
    "cancelled_at": null,
    "reason": null,
    "charged": null
  },
  "created_at": "2026-10-07T14:55:00.000Z",
  "updated_at": "2026-10-08T09:12:00.000Z"
}

409 Booking closed or too late to reschedule
422 Validation error

POST/bookings/{id}/cancel

Cancel a booking

Free until cancellation.free_until. Weather, a skipped port or an itinerary change are always free. Later cancellations for other reasons are charged in full. The response tells you whether it was charged.

Parameter	In	Type	Description
id*	path	string

Request

curl -X POST "https://app-api.smiler.co/api/partner/v1/bookings/IC-48213/cancel" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "guest_request",
    "note": "string"
  }'

Response 200

{
  "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
  "reference": "KD4BQHZR",
  "partner_reference": "IC-48213",
  "mode": "live",
  "status": "received",
  "product": {
    "id": 1234,
    "name": "Photoshoot in Paris",
    "duration_minutes": 60,
    "photos_included": 30
  },
  "city": "Paris",
  "country_code": "FR",
  "timezone": "Europe/Paris",
  "start_local": "2026-11-03T10:00",
  "end_local": "2026-11-03T11:00",
  "start_utc": "2026-11-03T09:00:00.000Z",
  "latest_end_local": "2026-11-03T13:30",
  "ship_name": "Sky Princess",
  "port": "Le Havre",
  "meeting_point": "Trocadéro fountains",
  "notes": "Anniversary",
  "guest": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "group_size": 2
  },
  "photographer": {
    "first_name": "Camille"
  },
  "guest_page_url": "https://smiler.co/b/KD4BQHZR",
  "gallery": {
    "url": "https://smiler.co/gallery/ab12cd34",
    "delivered_at": "2026-11-05T16:20:00.000Z"
  },
  "price": {
    "currency": "EUR",
    "retail": 229,
    "commission_pct": 20,
    "commission": 45.8,
    "net": 183.2
  },
  "cancellation": {
    "free_until": "2026-11-01T09:00:00.000Z",
    "cancelled_at": null,
    "reason": null,
    "charged": null
  },
  "created_at": "2026-10-07T14:55:00.000Z",
  "updated_at": "2026-10-08T09:12:00.000Z"
}

409 Booking already completed

POST/bookings/{id}/simulate

Test mode only: simulate what happens next

Parameter	In	Type	Description
id*	path	string

Request

curl -X POST "https://app-api.smiler.co/api/partner/v1/bookings/IC-48213/simulate" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "photographer_assigned"
  }'

Response 200

{
  "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
  "reference": "KD4BQHZR",
  "partner_reference": "IC-48213",
  "mode": "live",
  "status": "received",
  "product": {
    "id": 1234,
    "name": "Photoshoot in Paris",
    "duration_minutes": 60,
    "photos_included": 30
  },
  "city": "Paris",
  "country_code": "FR",
  "timezone": "Europe/Paris",
  "start_local": "2026-11-03T10:00",
  "end_local": "2026-11-03T11:00",
  "start_utc": "2026-11-03T09:00:00.000Z",
  "latest_end_local": "2026-11-03T13:30",
  "ship_name": "Sky Princess",
  "port": "Le Havre",
  "meeting_point": "Trocadéro fountains",
  "notes": "Anniversary",
  "guest": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "group_size": 2
  },
  "photographer": {
    "first_name": "Camille"
  },
  "guest_page_url": "https://smiler.co/b/KD4BQHZR",
  "gallery": {
    "url": "https://smiler.co/gallery/ab12cd34",
    "delivered_at": "2026-11-05T16:20:00.000Z"
  },
  "price": {
    "currency": "EUR",
    "retail": 229,
    "commission_pct": 20,
    "commission": 45.8,
    "net": 183.2
  },
  "cancellation": {
    "free_until": "2026-11-01T09:00:00.000Z",
    "cancelled_at": null,
    "reason": null,
    "charged": null
  },
  "created_at": "2026-10-07T14:55:00.000Z",
  "updated_at": "2026-10-08T09:12:00.000Z"
}

403 Live API key

Webhooks

POST/webhooks/test

Send a test `ping` event to your webhook URL

Request

curl -X POST "https://app-api.smiler.co/api/partner/v1/webhooks/test" \
  -H "Authorization: Bearer sk_test_…"

Response 200

{
  "delivered": true,
  "status": 1,
  "error": "string"
}

Webhooks

We send a POST to your webhook URL whenever a booking changes, whoever made the change. Each request carries Smiler-Event, Smiler-Delivery (unique id, use it to ignore duplicates) and Smiler-Signature. Respond with any 2xx status within 10 seconds; failed deliveries are retried after 1, 5, 15 minutes, then 1, 3, 6, 12 and 24 hours.

Event types:

booking.created — booking received
booking.confirmed — a photographer is assigned (first name and meeting point included)
booking.photographer_changed — a different photographer took over
booking.rescheduled — date or time changed
booking.cancelled — cancelled (by you or by Smiler support)
booking.completed — the shoot took place
booking.no_show — the guest did not show up
gallery.delivered — the online gallery is ready (booking.gallery.url)
ping — test event

Event payload

{
  "id": "b1e7c2a0-3f4d-4e5a-9b8c-7d6e5f4a3b2c",
  "type": "booking.confirmed",
  "mode": "live",
  "created_at": "2026-10-08T09:12:00.000Z",
  "data": {
    "booking": {
      "id": "5f2b8c1e-7a4d-4c1b-9e0f-2d6a3b8c9e10",
      "reference": "KD4BQHZR",
      "partner_reference": "IC-48213",
      "mode": "live",
      "status": "received",
      "product": {
        "id": 1234,
        "name": "Photoshoot in Paris",
        "duration_minutes": 60,
        "photos_included": 30
      },
      "city": "Paris",
      "country_code": "FR",
      "timezone": "Europe/Paris",
      "start_local": "2026-11-03T10:00",
      "end_local": "2026-11-03T11:00",
      "start_utc": "2026-11-03T09:00:00.000Z",
      "latest_end_local": "2026-11-03T13:30",
      "ship_name": "Sky Princess",
      "port": "Le Havre",
      "meeting_point": "Trocadéro fountains",
      "notes": "Anniversary",
      "guest": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+44 7700 900123",
        "group_size": 2
      },
      "photographer": {
        "first_name": "Camille"
      },
      "guest_page_url": "https://smiler.co/b/KD4BQHZR",
      "gallery": {
        "url": "https://smiler.co/gallery/ab12cd34",
        "delivered_at": "2026-11-05T16:20:00.000Z"
      },
      "price": {
        "currency": "EUR",
        "retail": 229,
        "commission_pct": 20,
        "commission": 45.8,
        "net": 183.2
      },
      "cancellation": {
        "free_until": "2026-11-01T09:00:00.000Z",
        "cancelled_at": null,
        "reason": null,
        "charged": null
      },
      "created_at": "2026-10-07T14:55:00.000Z",
      "updated_at": "2026-10-08T09:12:00.000Z"
    }
  }
}

Verify the signature (Node.js)

import crypto from 'node:crypto';

// Express: use the raw body, e.g. app.post('/smiler-webhook', express.raw({ type: 'application/json' }), handler)
function verifySmilerSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false;          // reject old events (replay)
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(parts.v1, 'hex'));
}

Objects

Booking

Field	Type	Description
id	string
reference	string	Smiler booking reference
partner_reference	string
mode	"live" \| "test"
status	Status
product	object
product.id	integer
product.name	string
product.duration_minutes	integer (nullable)
product.photos_included	integer (nullable)
city	string
country_code	string
timezone	string
start_local	string
end_local	string (nullable)
start_utc	string
latest_end_local	string (nullable)
ship_name	string (nullable)
port	string (nullable)
meeting_point	string (nullable)
notes	string (nullable)
guest	object
guest.name	string
guest.email	string (nullable)
guest.phone	string (nullable)
guest.group_size	integer
photographer	object (nullable)
photographer.first_name	string
guest_page_url	string (nullable)	Page for the guest: meeting point, chat with the photographer, live location on the day
gallery	object (nullable)
gallery.url	string (nullable)
gallery.delivered_at	string
price	object
price.currency	string
price.retail	number
price.commission_pct	number
price.commission	number
price.net	number
cancellation	object
cancellation.free_until	string
cancellation.cancelled_at	string (nullable)
cancellation.reason	string (nullable)
cancellation.charged	boolean (nullable)
created_at	string
updated_at	string (nullable)

Product

Field	Type	Description
id	integer
name	string
city	object
city.name	string
city.slug	string
country_code	string
timezone	string
tier	string (nullable)
duration_minutes	integer (nullable)
photos_included	integer (nullable)
meeting_point	string (nullable)
retail_price	number
commission_pct	number
net_price	number	What you pay us: retail price minus your commission
currency	string

CreateBooking

Field	Type	Description
partner_reference*	string	Your booking reference, unique per account
product_id*	integer
start_local*	string	Local time at the shoot location
latest_end_local	string	Optional: the guest must be done by then (e.g. all-aboard time minus travel)
guest*	object
guest.name*	string
guest.email	string
guest.phone	string
group_size	integer
meeting_point	string
notes	string
ship_name	string
port	string

Error

Field	Type	Description
error	object
error.code	string
error.message	string
error.details	object