Authentication ¶

The MadeWithBree Website API uses Bearer Token Authorization

1. You can view your API key in your website > Website Settings > Applications > API Key.

2. You can use your API key to access protected resources in your website only by passing the Authorization header:

   Authorization: Bearer <API KEY>

3. All API requests must be made over HTTPS

Errors ¶

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a resource was missing, etc.). Codes in the 5xx range indicate a serer error or an unprocessable entry.

Every error include a human-readable message:

{
    success: false,
    message: "Error message..."
}

Pagination ¶

Most API endpoints returning multiple objects (lists) support pagination. These lists share a common structure and can take at least these two parameters:

List response format:

{
    items: [
        { ... },
        { ... },
        { ... }
    ],
    totalCount: 10,
    limit: 25,
    skip: 0
}

Contacts ¶

Contacts are all visitors identified by their email in your website

Contact attributes:

Members ¶

Members are registered users in your website.

Member attributes:

Member address is described as:

Address attributes:

Member groups ¶

Member groups are groups which the members belongs to. Access to resources can be restricted to specific member groups only.

Member groups attributes:

Products ¶

Products are individual items, services or memberships for sale in your store.

Product attributes:

Store Category attributes:

Each product can have multiple options, ex: Color, Size, Material, etc with each option having multiple values, ex: Size - Small, Medium, Large.

Product options are described as:

Product Option attributes:

If multiple versions of a product (different variants) have different price, quantity, SKU or weight, each product option can be marked as advanced. Setting product option as advanced will enable custom price / quantity / SKU or weight for each of the option variants.

All products have at least one variant, described as:

Product Variant attributes:

Store products can have a mix of advanced and non-advanced options.

For example, the price can be determined by Material and Size but not by the color of the product with the following options:

{
  "name": "Material",
  "values": ["Metal", "Wood"],
  "advanced": true
},
{
  "name": "Size",
  "values": ["Small", "Large"],
  "advanced": true
},
{
  "name": "Color",
  "values": ["Green", "Blue"],
  "advanced": false
}

When setting up the product variant, include the value of the advanced options only.

Example for the product variants from above:

{
    "options": ["Metal", "Small"],
    "price": 10
},
{
    "options": ["Metal", "Large"],
    "price": 10
},
{
    "options": ["Wood", "Small"],
    "price": 10
},
{
    "options": ["Wood", "Large"],
    "price": 10
},

Use empty array ([]) for options when there are no advanced variants, setting the price / quantity / sku for the whole product.

Subscription attributes:

If multiple versions of a product (different variants) have different price, quantity, SKU or weight, each product option can be marked as advanced. Setting product option as advanced will enable custom price / quantity / SKU or weight for each of the option variants.

All products have at least one variant, described as:

Orders ¶

Access orders placed in your website.

Order attributes:

Each Order consists of one or more order items. Described as:

Order Item attributes:

Customer Addresses are described as:

Address attributes:

Forms ¶

Access all form submissions in the website. Each form submission is described as:

Form submission attributes:

Bookings ¶

Access the details of all scheduled events via the booking features of each website or funnel.

Booking attributes:

EventDetails attributes:

Operator attributes:

Service attributes:

Webhooks ¶

Webhooks are a system of automated notifications indicating that an event has occurred in your website. Rather than requiring you to pull information via the API, webhooks push information to your destination when important events occur.

You can create webhooks for:

• New Order (order_created) - fired when a new order is placed on the website

• Updated Order (order_updated) - fired when an order is updated

• New Product (product_created) - fired when a new product is created

• Updated Product (product_updated) - fired when a product is updated

• New Form Submission (form_submitted) - fired when a form is submitted

• New Contact Activity (contact_updated) - fired when a new contact is created or existing contact is updated

• New Booking Created (booking_created) - fired when a new booking is created

When one of the selected events is triggered, we’ll send a HTTP POST payload to the webhook’s target URL. The payload is a single JSON object and depends on the event:

Each POST call to your destination URL will include the following headers:

If a POST request fail, we’ll send an email to the owner of the website to notify them for the failed webhook.

Each request to your destination URL is signed using the webhook secret. The signature is passed in the X-Webhook-Signature header and can be used to verify that the events were sent by us and not by a third party. To verify the signature, generate the HMAC hex digest using the SHA-512 hash function and the webhook secret as the HMAC key. Then compare it with the X-Webhook-Signature from the request.

The POST Payload for New Form Submission is as follows:

{
    "website": 
    {
        "id": 123,
        "subdomain": "some-subdomain",
        "systemDomain": "your-system.subdomain.com"
        "domain": "your-primary-domain.com"
    },
    "contact": { ... },
    "formName": "Contact Form",
    "formValues": [
        {"field": "Name", "value": "John"},
        {"field": "Email","value": "john@doe.com"}
    ]
}

Where each attribute is:

Managing Webhooks via the API ¶

Webhooks can be created and deleted via this API.

Each webhook is described as:

Webhook attributes: