Festivalcadeau Developer API

Welcome to the Festivalcadeau Developer API documentation. Integrate your events, accept giftcard payments, and manage your listings on our platform.

Payment Integration

Accept Festivalcadeau giftcard payments in your checkout. No payment gateway needed, just call our API directly.

Payment Flow

Overview of how giftcard payments work for domestic and international partners.

Devalue Card

Deduct value from a giftcard. Returns a one-time cancel token for refunds.

Cancel Devalue

Reverse a deduction and reload the card when a customer abandons checkout.

Check Balance

Check a card's balance and status before deducting.

Event API

There are two ways to integrate your events with Festivalcadeau. We recommend exposing a public API so we can pull your events, but both options are fully supported.

Pull Events from Your System

Expose a public API endpoint and we pull your events automatically. Recommended: less maintenance on your end.

Inject Events into Our System

Push events directly to our API. You control when events are created and updated.

API Structure Requirements

To integrate with Festivalcadeau, your API must expose event data in a structured format. Below are the required fields and formats your API should support.

Event Model Specification

Your API must be able to provide event details with the following structure. If this cannot be done, please contact Festivalcadeau to find a suitable solution.

{
    "events": [
        {
            "event_id": "Unique Event Identifier",       // required
            "banner": "URL_to_event_banner_image",
            "poster": "URL_to_event_poster_image",
            "title": "Event Title",                       // required
            "description": "Event Description",
            "organiser": "Organiser's Name or ID",
            "date": "YYYY-MM-DD",                         // required (must be today or future)
            "time": "HH:MM",
            "end_date": "YYYY-MM-DD",
            "end_time": "HH:MM",
            "location": {                                 // required
                "streetname": "Street Name",
                "streetnumber": "Street Number",
                "zipcode": "Postal Code",
                "city": "City",
                "state": "State or Province",
                "country": "Country",
                "building": "Venue Building Name"
            },
            "minimum_age": 18,
            "genre": "Event Genre",
            "price": 50.00,
            "shopurl": "URL_to_ticket_purchase_page",
            "ticket_link": "Direct link to tickets",     // required
            "url": "Event Page URL",
            "video_link": "URL_to_event_video"
        }
    ]
}
Ensure your API endpoint serving this data is accessible and adheres to these specifications for seamless integration with Festivalcadeau.

Getting Started

Follow these steps to start pushing events to the Festivalcadeau platform using our API.

  1. Authenticate
    Authenticate with your credentials to receive an API key. Keep this key secure, it's required for all subsequent requests.
  2. Get Ticketing Provider IDs
    Retrieve all ticketing providers available on Festivalcadeau. You'll need a provider ID when creating events.
  3. Create Event Concepts
    Create an Event Concept, which acts as a container (organiser) under which you group individual events.
  4. Create Events
    Create events under your Event Concept. Provide the event name, date, location, and your Event Concept ID.
  5. Manage & Review
    Retrieve your events and event concepts at any time to verify your data.