Deals Marketplace API Guide

Authentication

Authenticate with the reseller api_key Fave issued for your account. Pass it as a query parameter on every request. No password is required.

Example

GET /api/marketplace/v2/cities/kuala-lumpur/listings?api_key=YOUR_API_KEY

Requirement	Detail
API access	Your reseller account must have Deals Marketplace API enabled (`api_enabled`).
Purchase access	Creating reservations also requires purchase API enabled on your account.
Transport	HTTPS only. Plain HTTP requests fail.

Missing or invalid keys, or API not enabled, return 401 with Unauthorized.

Cities

The city path segment selects the market for deals and reservations.

City slug	Market
`kuala-lumpur`	Malaysia
`singapore`	Singapore

Unsupported city values return 400 with City Unsupported. Jakarta is not available on this API.

List deals

Returns current deals in a city, including merchant and outlet details. Only open-voucher deals available on the Deals Marketplace channel are returned. Deals restricted to specific resellers are filtered to your account.

GET /api/marketplace/v2/cities/{city}/listings

Path parameters

Name		Description
`city`	required	`kuala-lumpur` or `singapore`

Query parameters

Name		Description
`api_key`	required	Reseller API key
`status`	optional	`active` (default) or `inactive`
`page`	optional	Pagination page. Default `1`
`limit`	optional	Page size. Default `25`, maximum `25`
`updated_after`	optional	ISO 8601 datetime. Only deals updated on or after this time. Encode `+` in the timezone as `%2B` (see Appendix)
`latitude` / `longitude`	optional	User coordinates. Improves distance ranking when provided together
`order`	optional	`created_at`, `updated_at`, `live_at`, or `distance` (requires lat/lng). Omit for Fave recommendation ranking
`main_category`	optional	Filter by category slug, for example `eat`, `beauty`, `massage`, `activity`, `charity`, `retail`, `service`, `travel`

Example response

200 OK

{
  "listings": [
    {
      "id": 4,
      "name": "Purple Enormous Copper Bottle",
      "status": "active",
      "purchasable": true,
      "labels": ["eye-lash"],
      "main_category_type": "beauty",
      "main_category_type_title": "Beauty",
      "main_category": { "id": 1, "name": "Beauty" },
      "company": {
        "id": 2,
        "name": "Example Spa",
        "average_rating": 4.5,
        "description": "…",
        "featured_image": "https://…",
        "featured_thumbnail_image": "https://…",
        "gallery_images": [],
        "profile_icon_image": "https://…"
      },
      "outlets": [
        {
          "id": 2,
          "name": "KLCC",
          "address": "Jl. Ahmad Yani No. 95",
          "gmap_address": null,
          "city": "Kuala Lumpur",
          "town": "KLCC",
          "coordinates": "3.1379835, 101.6582551",
          "neighbourhood": null
        }
      ],
      "purchase_details": {
        "discounted_price": "RM24.48",
        "original_price": "RM54.57",
        "savings": "RM30.09",
        "savings_percentage": 55,
        "total_chargeable_amount": "RM24.48",
        "total_chargeable_amount_minor_value": 2448
      },
      "voucher_details": {
        "start_datetime": "2021-03-15 09:34:21 +0800",
        "end_datetime": "2021-06-13 23:59:59 +0800",
        "redeemable_from": "2021-03-15 09:34:21 +0800",
        "redeemable_to": "2021-06-13 23:59:59 +0800"
      },
      "quantity_cap": 100,
      "purchase_cap": 100,
      "remaining_daily_capacity": 10000,
      "one_link_url": "https://myfave.onelink.me/…",
      "description": "…",
      "fine_print": "…",
      "what_you_get": "…",
      "redemption_instructions": "…",
      "advanced_booking_requirement": "…",
      "cancellation_policy": "…",
      "featured_image": null,
      "featured_thumbnail_image": null,
      "gallery_images": [],
      "validity_times": null
    }
  ],
  "meta": {
    "results": 38
  }
}

purchase_details.total_chargeable_amount_minor_value is the amount you should charge in the smallest currency unit (MYR/SGD cents). Listing amounts include any applicable guarantee fee.

Get deal

Returns a single deal by id, with the same deal object shape as list deals (no listings wrapper).

GET /api/marketplace/v2/cities/{city}/listings/{id}

Path parameters

Name		Description
`city`	required	`kuala-lumpur` or `singapore`
`id`	required	Deal id from list deals

Query / body parameters

Name		Description
`api_key`	required	Reseller API key

Example response

200 OK

{
  "id": 4,
  "name": "Purple Enormous Copper Bottle",
  "status": "active",
  "purchasable": true,
  "labels": ["eye-lash"],
  "main_category_type": "beauty",
  "main_category_type_title": "Beauty",
  "main_category": { "id": 1, "name": "Beauty" },
  "company": {
    "id": 2,
    "name": "Example Spa",
    "average_rating": 4.5,
    "description": "…",
    "featured_image": "https://…",
    "featured_thumbnail_image": "https://…",
    "gallery_images": [],
    "profile_icon_image": "https://…"
  },
  "outlets": [
    {
      "id": 2,
      "name": "KLCC",
      "address": "Jl. Ahmad Yani No. 95",
      "gmap_address": null,
      "city": "Kuala Lumpur",
      "town": "KLCC",
      "coordinates": "3.1379835, 101.6582551",
      "neighbourhood": null
    }
  ],
  "purchase_details": {
    "discounted_price": "RM24.48",
    "original_price": "RM54.57",
    "savings": "RM30.09",
    "savings_percentage": 55,
    "total_chargeable_amount": "RM24.48",
    "total_chargeable_amount_minor_value": 2448
  },
  "voucher_details": {
    "start_datetime": "2021-03-15 09:34:21 +0800",
    "end_datetime": "2021-06-13 23:59:59 +0800",
    "redeemable_from": "2021-03-15 09:34:21 +0800",
    "redeemable_to": "2021-06-13 23:59:59 +0800"
  },
  "quantity_cap": 100,
  "purchase_cap": 100,
  "remaining_daily_capacity": 10000,
  "one_link_url": "https://myfave.onelink.me/…",
  "description": "…",
  "fine_print": "…",
  "what_you_get": "…",
  "redemption_instructions": "…",
  "advanced_booking_requirement": "…",
  "cancellation_policy": "…",
  "featured_image": null,
  "featured_thumbnail_image": null,
  "gallery_images": [],
  "validity_times": null
}

Returns 404 with Deal not found when the deal is missing, not on the Deals Marketplace channel, or not available to your reseller.

Create reservation

Purchases vouchers from an active Deals Marketplace deal and returns reservation details plus a redemption URL.

POST /api/marketplace/v2/cities/{city}/reservations

Query / body parameters

Name		Description
`api_key`	required	Reseller API key
`deal_id`	required	Deal id from listings
`name`	required	Customer name. If you cannot share PII, ask Fave for a representative name
`email`	conditional	Required if `phone` is blank. Used to associate the customer and optionally email the redemption link. See representative email if you cannot share customer emails
`phone`	conditional	Required if `email` is blank. Include country code, e.g. `60123456789`
`quantity`	optional	Number of vouchers. Default `1`
`deliver`	optional	`true` / `false`. When `true` and an email is present, Fave emails the redemption link. Default `false`
`order_id`	optional	Your reference to associate with the reservation

Example response

200 OK

{
  "reservation": {
    "id": 291,
    "redeemable_from": "2021-04-15T17:20:57+08:00",
    "redeemable_to": "2021-07-14T23:59:59+08:00",
    "redeemable_url": "https://vouchers.myfave.com/cities/kuala-lumpur/redeem/291/rs-yj1h99b",
    "redemption_status": "confirmed",
    "status": "successful",
    "transaction_details": {
      "discounted_price": "RM35.96",
      "original_price": "RM55.62",
      "savings": "RM19.66",
      "savings_percentage": 35,
      "total_chargeable_amount": "RM35.96",
      "total_chargeable_amount_minor_value": 3596
    },
    "deal": {
      "id": 17,
      "name": "Indigo Ergonomic Wooden Bag",
      "status": "active",
      "purchasable": true
    }
  }
}

The nested deal object uses the full deal object shape.

redeemable_url is a web redemption page. Open it in a webview (or in-app browser) so the customer can redeem the voucher. Do not treat it as a deep link into the Fave app.

Redemption status

redemption_status is the voucher lifecycle. After a successful create it is confirmed. Poll Get reservation (or wait for a callback) for later changes.

Value	When
`confirmed`	Default after purchase. Voucher is unused and can still be redeemed
`redeemed`	Customer has redeemed the voucher
`cancelled`	Reservation was cancelled

Unsupported HTTP methods on this path return 405 with Unsupported Method.

Get reservation

Returns the current state of a reservation by reservation id (the id from create reservation).

GET /api/marketplace/v2/cities/{city}/reservations/{reservation_id}

Path parameters

Name		Description
`city`	required	`kuala-lumpur` or `singapore`
`reservation_id`	required	Reservation id from create reservation

Query / body parameters

Name		Description
`api_key`	required	Reseller API key

Example response

200 OK

{
  "reservation": {
    "id": 291,
    "redeemable_from": "2021-04-15T17:20:57+08:00",
    "redeemable_to": "2021-07-14T23:59:59+08:00",
    "redeemable_url": "https://vouchers.myfave.com/cities/kuala-lumpur/redeem/291/rs-yj1h99b",
    "redemption_status": "confirmed",
    "status": "successful",
    "transaction_details": {
      "discounted_price": "RM35.96",
      "original_price": "RM55.62",
      "savings": "RM19.66",
      "savings_percentage": 35,
      "total_chargeable_amount": "RM35.96",
      "total_chargeable_amount_minor_value": 3596
    },
    "deal": {
      "id": 17,
      "name": "Indigo Ergonomic Wooden Bag",
      "status": "active",
      "purchasable": true
    }
  }
}

The nested deal object uses the full deal object shape. Open redeemable_url in a webview (or in-app browser) for web redemption.

redemption_status uses the same values as create reservation: confirmed, redeemed, or cancelled. See Create reservation and the reservation object.

Callbacks

When enabled for your account, Fave notifies your callback URL when a voucher is redeemed or cancelled. Provide production and sandbox callback URLs during onboarding.

Callback format is partner-specific. The signed JSON contract below is used for integrations that opt into the Deals Marketplace callback profile (mTLS + detached JWS). Other partners may use a simpler POST to their callback URL, and Fave confirms the format for your account.

Signed callback request (Deals Marketplace profile)

POST https://callback.partner/deal/status

Headers

Header		Description
`Content-Type`	required	`application/json`
`Accept`	required	`application/json`
`Application-ID`	required	Application id you provide to Fave
`API-Key`	required	API key you provide to Fave
`Client-ID`	required	Client id for JWT certificate selection
`Authorization`	required	Detached JWS (RS256) of the payload
`Country`	required	Country routing flag, e.g. `SG`

Body

JSON body

{
  "transactionReference": "abcdefghij123456789",
  "activation_code": "as-38uj",
  "reservation_id": "1",
  "redemption_status": "redeemed"
}

Field	Description
`transactionReference`	19-character alphanumeric reference for this callback
`activation_code`	Code from the reservation `redeemable_url`
`reservation_id`	Reservation id as a string
`redemption_status`	`redeemed` or `cancelled`

The body key is transactionReference (camelCase). Use the same field names when reconstructing the payload to verify the detached JWS.

mTLS

Fave calls your endpoint with a Sectigo-CA signed client certificate. Add the Sectigo RSA Domain Validation Secure Server CA intermediate to your trust store, and share any intermediate/root certs Fave needs to trust your server.

Detached JWS

Fave signs the payload with RS256, then removes the middle (payload) segment so Authorization looks like header..signature. To verify:

Rebuild the exact JSON payload from the request body (same key order/values as received).
Re-insert the Base64URL-encoded payload into the JWS middle segment.
Verify the signature with the JWT public certificate Fave shared with you.

Reference: RFC 7515 Appendix F.

Expected success response

Partner → Fave

{
  "code": "0000000"
}

Return HTTP 200 with code 0000000 when the callback was processed. Fave retries on 5xx (up to 3 attempts).

Deal object

Returned in list deals, get deal, and nested under reservations.

Field	Description
`id`	Deal id, which is required for create reservation
`status`	Deals Marketplace status, typically `active` or `inactive`
`purchasable`	Whether the deal can be purchased now
`outlets`	Active outlets where the voucher can be redeemed
`purchase_details`	Formatted prices and `total_chargeable_amount_minor_value`
`voucher_details`	Sale and redeemable date window
`labels`	Deal labels / tags
`main_category`	`{ id, name }`
`one_link_url`	Deep link / web link for the deal

Reservation object

Field	Description
`id`	Reservation id
`status`	Payment status. On successful create: `successful`
`redemption_status`	`confirmed` (default after purchase), `redeemed`, or `cancelled`. See Create reservation
`redeemable_from` / `redeemable_to`	Redemption validity window (ISO 8601)
`redeemable_url`	Webview URL for voucher redemption. Production host: `https://vouchers.myfave.com/cities/{city}/redeem/{id}/{activation_code}`
`transaction_details`	Charged amounts for this reservation (same shape as deal `purchase_details`)
`deal`	Full deal object for the purchased listing

Use the JSON field name redeemable_url (not redemption_url).

Errors

Error responses use code (HTTP status) and message.

Example

{
  "code": 401,
  "message": "Unauthorized"
}

Common

HTTP	Message	When
`401`	`Unauthorized`	Missing/invalid `api_key`, API not enabled, or purchase API not enabled (create only)
`400`	`City Unsupported`	Invalid city path
`405`	`Unsupported Method`	HTTP method not allowed on reservations

Listings

HTTP	Message
`400`	`updated_after format is invalid`
`400`	`latitude or longitude format is invalid`
`400`	`Invalid main category`
`404`	`Deal not found`

Reservations

HTTP	Message
`400`	`User's name is required`
`400`	`Deal's ID is required`
`400`	`At least one of email or phone is required`
`400`	`Deal not found`
`400`	`Deal is either inactive or expired or not listed in marketplace`
`400`	Capacity / purchase failures (message from transaction layer)
`404`	`ReservationSet not found`, `EagleReservation not found`, `EagleActivity not found`, or `ResellerCode not found`

Appendix

URL-encode query parameters

Encode reserved characters in query values. A plus sign in emails or timezones is parsed as a space unless encoded as %2B.

foobar+representative@myfave.com → foobar%2Brepresentative@myfave.com
2021-01-18T17:00:00+08:00 → 2021-01-18T17:00:00%2B08:00

Representative email

If you cannot share customer emails, ask Fave for a representative email for your reseller account, typically:

Example

your-organization+representative@myfave.com

URL-encode the +. When using a representative email, omit deliver, because Fave will not email a real customer.

What changed vs the old PDF

Jakarta is not a supported city on this API.
Reservation URL field is redeemable_url.
Inactive/expired create error includes or not listed in marketplace.
Void / cancel reservation is not available on Deals Marketplace v2.
Signed callback body uses transactionReference (camelCase).
This page is the live partner reference; there is no separate public PDF revision number.

Support

Need API keys, sandbox access, representative email, callback credentials, or help with an integration issue? Contact your Fave technical contact or Partnership Manager.