Documentation
Email CampaignsWebsite PersonalizationMobile AppsWeb PushLoyalty Program

Custom integration

Overview

Custom Integration: 3 Key Steps

  1. Install the JavaScript SDK Tracker
  2. Integrate Frontend API Calls
    • Website.AuthorizeCustomer
    • Website.ViewProduct
    • Website.ViewCategory
    • Website.SetCart
  3. Integrate Backend API Calls
    • Website.RegisterCustomer
    • Website.EditCustomer
    • Website.UpdateOrder
  4. Generate a product feed file.
⚠️

Warning:
All API requests on this page are examples.

The names of API methods and some fields may differ in your account.
Please contact your Maestra Forward Deployed Marketer to obtain account-specific technical documentation.

Customer Profile API

POST How to Register a Profile

When a new customer profile is created in your website's database, at least one of the following identifiers must be provided:

  • ID
  • email
  • phone number

Other customer details are optional for Maestra API.`

Example Request

POST 

https://api.maestra.io/v3/operations/async?endpointId={integration point ID}&operation=Website.RegisterCustomer&deviceUUID={device UUID}

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Maestra secretKey="{secret key}"
User-Agent: {User-Agent of the customer's device}

{
  "customer": {
    "mobilePhone": "<Mobile phone>",
    "email": "<Email>",
    "ids": {
      "websiteID": "<Website ID>"
    },
    "sex": "<Gender>",
    "lastName": "<Last name>",
    "firstName": "<First name>",
    "middleName": "<Middle name>",
    "birthDate": "<Birthdate>",
    "subscriptions": [
      {
        "brand": "<System name of the brand the customer is subscribed to>",
        "pointOfContact": "<System name of the subscription channel>",
        "topic": "<External ID of subscription subject>"
      },
      {
        "brand": "<System name of the brand the customer is subscribed to>",
        "pointOfContact": "<System name of the subscription channel>",
        "topic": "<External ID of subscription subject>"
      }
    ]
  }
}

How to authorize a customer

This script is triggered as soon as a customer successfully logs in to the website.

Example Request

maestra("async", {
  operation: "Website.AuthorizeCustomer",
  data: {
    customer: {
      ids: {
        websiteID: "<Website ID>"
      }
    }
  }
});

POST How to Edit Customer Profile Details

This API method is called when the customer updates their profile details.

Example Request

POST 

https://api.maestra.io/v3/operations/{sync/async}?endpointId={integration point ID}&operation=Website.EditCustomer&deviceUUID={device UUID}


Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Maestra secretKey="{secret key}"
User-Agent: {User-Agent of the customer's device}

{
  customer: {
    "ids": {
      websiteID: "<Website ID>"
    },
    "birthDate": "<Birthdate>",
    "sex": "<Gender>",
    "lastName": "<Last name>",
    "firstName": "<First name>",
    "middleName": "<Middle name>",
    "email": "<Email>",
    "mobilePhone": "<Mobile phone>",
    "subscriptions": [
      {
        "brand": "<System name of the brand the customer is subscribed to>",
        "pointOfContact": "<System name of the subscription channel: Email, SMS, Viber, Webpush, Mobilepush>",
        "topic": "<External ID of subscription subject>",
        "isSubscribed": "<Value of the subscription the customer specified in the form>"
      },
      {
        "brand": "<System name of the brand the customer is subscribed to>",
        "pointOfContact": "<System name of the subscription channel: Email, SMS, Viber, Webpush, Mobilepush>",
        "topic": "<External ID of subscription subject>",
        "isSubscribed": "<Value of the subscription the customer specified in the form>"
      }
    ]
  }
}

What You Can Do With Products API

Product view

This method is triggered from the product detail page.
The submitted websiteId must match a product that was previously imported into Maestra—either via bulk XML/CSV import or through a real-time update.

Example Request

maestra("async", {
  operation: "Website.ViewProduct",
  data: {
    viewProduct: {
      product: {
        ids: {
          website: "<Id product to website>"
        }
      }
    }
  }
});

Browsing a Category

This method is triggered from the product category page.
The submitted websiteId must match product category that was previously imported into Maestra—either via bulk XML/CSV import or through a real-time update.

Example Request

maestra("async", {
  operation: "Website.ViewCategory",
  data: {
    viewProductCategory: {
      productCategory: {
        ids: {
          website: "<Id Product Category to website>"
        }
      }
    }
  }
});

Setting up the cart

This script is triggered every time the cart is updated — whether products are added or removed, quantities change, prices are updated, or the cart is cleared.
Each product should only be transferred once, along with its quantity and total price (based on that quantity).

Example Request

maestra("async", {
  operation: "Website.SetCart",
  data: {
    productList: [
      {
        product: {
          ids: {
            website: "<Id product to website>"
          }
        },
        count: "<Number of items>",
        pricePerItem: "<Price per item>"
      },
      {
        product: {
          ids: {
            website: "<Id product to website>"
          }
        },
        count: "<Number of items>",
        pricePerItem: "<Price per item>"
      }
    ]
  }
});

Orders API

POST Update order

If the customer doesn’t exist in the CDP, Maestra will create a new customer and add the order to their account.
If the user already exists, the order will be added to their account, and their profile will be updated if needed. This method can also be used to update the order status.

Example Request

POST 

https://api.maestra.io/v3/operations/async?endpointId={Integration point ID}&operation=Website.UpdateOrder


Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Maestra secretKey="{secret key}"
User-Agent: {User-Agent of the customer's device}

{
  "customer": {
    "ids": {
      "websiteID": "<Website ID>"
    }
  },
  "order": {
    "ids": {
      "websiteID": "<Order ID Order ID on the website>"
    },
    "deliveryCost": "<Cost of order delivery>",
    "customFields": {
      "deliveryType": "<Method of delivery>"
    },
    "totalPrice": "<Total amount received from the customer.. It must allow for returns and cancellations. It is used to calculate an average order amount.>",
    "discounts": [...],
    "lines": [
      {
        "basePricePerItem": "<Basic cost of a product item>",
        "quantity": "<Quantity of SKUs (or items if no SKUs are transferred)>",
        "discountedPricePerLine": "<Total cost for an entire line on a receipt, with all discounts calculated>",
        "discounts": [...],
        "product": {
          "ids": {
            "website": "<Id Product to website>"
          }
        },
        "status": "<Status of order line>"
      },
      {
        "basePricePerItem": "<Basic cost of a product item>",
        "quantity": "<Quantity of SKUs (or items if no SKUs are transferred)>",
        "discountedPricePerLine": "<Total cost for an entire line on a receipt, with all discounts calculated>",
        "discounts": [...],
        "product": {
"ids": {
            "website": "<Id Product to website>"
          }
        },
        "status": "<Status of order line>"
      }
    ],
    "email": "<Email>",
    "mobilePhone": "<Unformatted number of the mobile phone>"
  },
  "executionDateTimeUtc": "<UTC date & time of execution>"
}

Product feed setup

Consult with your Maestra marketer to determine the feed format best suited for your account.
The appropriate format depends on the number of product data sources and which system serves as the backend.
For example, it could be a Google Merchant feed or an out-of-the-box integration.

Updated 16 days ago