Integration guide

This part of prebooking documentation will guide you through the integration guide with prebooking feature. After getting familiar with this section, you will:

learn how to integrate with prebooking,
see how webhooks are leveraged for prebooking mechanism,
gain knowledge about the prebooking message format.

Requirements

In order to use the prebooking callbacks to your API, it needs to meet the following requirements:

consume the message format (can be configured with field exclusion, more information in message format subsection),
consume JSON,
support authorization with bearer token,
communicate over HTTPS.

The URL of the endpoint to which the prebooking callbacks will be made has to be added to prebooking configuration.

Prebooking mechanism is implemented with webhooks. Webhook is fired every time a customer converts (finalizes the order) to an endpoint provided in the prebooking configuration. Each webhook contains a unique identifier and set of fields related to the finalized order. More about the fields in the message payload can be found in the message format subsection and Reference section.

Rate limiting

Prebooking webhooks are rate limited. Rate limits are set per month and are lifted at the beginning of each month. To learn more about rate limits, contact us here. We provide both paid tier and free tier of this service with generous number of prebooking webhooks to be used per month. 🎁

Message format

Prebooking webhook messages are sent in the following format as JSON. To learn more about the exact fields and types, please consult the Reference section.

{
  "prebooking-id": "carrier-product:1112331323421",
  "triggered_at": "2021-04-09T15:00:00Z",
  "meta": {
    "merchant_id": "merchant-identifier-from-mapping",
    "another_field": "value"
  },
  "session": {
    "cart": {
      "items": [
        {
          "sku": "a3ec72d0-836f-4668-9c54-5c86d67ca897",
          "name": "Keyboard",
          "out_of_stock": false,
          "quantity": 1
        }
      ],
      "pre_order": false
    },
    "purchase_country": "SE",
    "additional_information": {
      "courier_instructions": "Look out for the dog",
      "door_code": "12345",
      "customer_number": "123"
    },
    "customer": {
      "address": {
        "name": "Ingrid Tester",
        "address_lines": ["Skeppargatan 65"],
        "city": "Stockholm",
        "postal_code": "11459",
        "country": "SE",
        "coordinates": {
          "lat": 59.340663,
          "lng": 18.087994
        }
      },
      "phone": "12356789",
      "email": "test@ingrid.com"
    },
    "result": {
      "shipping": {
        "shipping_method": "carrier-product",
        "delivery_type": "delivery",
        "carrier": "Carrier company",
        "product": "Carrier product",
        "supports": {},
        "meta": {
          "additional_optional_information_from_carrier": "21e43116-6a66-4c23-bbb5-71e4f8f9419d"
        },
        "warehouse": {
          "address": {
            "name": "Ingrid Tester",
            "address_lines": ["Skeppargatan 65"],
            "city": "Stockholm",
            "postal_code": "11459",
            "country": "SE",
            "coordinates": {
              "lat": 59.340663,
              "lng": 18.087994
            }
          }
        }
      },
      "selection": "PRESELECTED_CHOICE",
      "delivery_time": {
        "pickup_from_merchant": {
          "earliest": "2021-04-08T20:00:00+02:00",
          "latest": "2021-04-08T20:00:00+02:00"
        },
        "customer_delivery_promise": {
          "earliest": "2021-04-10T15:00:00Z",
          "latest": "2021-04-10T19:00:00Z"
        },
        "carrier_delivery_promise": {
          "earliest": "2021-04-10T15:00:00Z",
          "latest": "2021-04-10T19:00:00Z"
        }
      }
    }
  }
}

You can configure the message format to exclude a subset of fields from it. To do so, please contact Ingrid Support Team.

Meta field

You can push arbitrary data throughout a checkout flow in Ingrid. When Ingrid fetches shipping options from carrier API before showing the checkout widget to an end-customer, additional data may be added to the carrier-related options. This information can be added to meta field in the prebooking message.

Identifying merchants

You can configure the unique identifier that describes the merchant for which the order has been made. If the merchant identifier is provided in the prebooking configuration, it will be added to the meta field under merchant_id key.

Configuration

Configuration of your prebooking setup is done by Ingrid Support Team.

Support Team contact

You can contact Support Team here. We can guide you through steps needed to start using prebooking feature. Don't hesitate to reach out to us if you have additional questions!

The following things can be configured for the prebooking feature:

prebooking message field exclusion,
merchant identifier mapping,
prebooking callback URL,
bearer token used for prebooking callbacks with webhooks,
meta field content.

Security

Your endpoint should support a bearer token authorization to ensure that messages come from Ingrid. Moreover, the endpoint should support HTTPS, because making requests over an HTTP connection may leak the bearer token.

Last updated: Thu, Nov 21, 06:15 AM