Skip to content

Custom Endpoints

GEThttps://rebuyengine.com/api/v1/custom/id/{ Ruleset ID }

Requirements

To use this endpoint you must add a valid ruleset ID to /api/v1/custom/id/{ Ruleset ID }

Using Rebuy's GUI

You can use our GET /api/v1/custom/id/{ Ruleset ID } endpoint through our Graphical User Interface (GUI). We allow access to this feature with what we call data sources. In data sources, you can create a set of conditional rules (ie. a ruleset). If those conditions are met by one of your customers, this endpoint will return them a list of products.

Once created, data sources can be applied to power widgets. However, this page doesn't go into detail on how to create and use widgets.

First, log into Rebuy Engine\ In the left navigation bar, select Data Sources

Alt text

Creating Rulesets

To create a ruleset, select the Create Ruleset button.

Alt text

After creating a ruleset, you can set your first rule. Rulesets can be powered by only one rule, or you can choose to stack multiple rules for further customization.

Alt text

For each rule block, there is an "IF" condition and a "RETURN" statement.

Alt text

"IF" conditions

For each "IF" condition, you define parameters that can tell us when a certain condition is met.

Alt text

This is where our GUI and endpoint synchronize so well. At this stage, you are literally defining what information you are sending to our API.

You can make your "IF" condition more complex if you add "AND IF" or "OR IF" statements into the rule.

Alt text

"RETURN" statements

For each "RETURN" Statement, you define parameters that can tell our API what to return to your customer. This is another area where our GUI and endpoint synchronize so well. At this stage, you are literally defining what information you are receiving from our API.

Alt text

You can make your "RETURN" statements more complex if you add "AND" statements into the rule.

Alt text

Example Data Sources

Below you will find some great ways that our clients have effectively used this feature.

The associated upsell

In the example below, if the grooming kit is chosen by the customer, we will display them some essentials that go along with the kit. In other words, your shop is ready to sell them a product and as a result we want to upsell them another product.

Alt text

More Reading

Read more on widgets

Query Parameters

shopify_product_ids · string
Comma separated list of Shopify product IDs. Also used if only passing up single product ID.
Allows for product level rules in your Data Source
shopify_variant_ids · string
Comma separated list of Shopify variant IDs of a product. Also used if only passing up single variant ID.
Allows for variant level rules in your Data Source.
shopify_customer_id · string
The Customer ID of the Shopify user.
cart_subtotal · string
The total cost of items inside the cart.
cart_line_count · string
A single line in an order. There is one line item for each product variant.
cart_item_count · string
The number of items inside the cart.
metafields · string
Valid values: yes. Returns product objects enriched with a metafields property.
variant_metafields · string
Valid values: yes. Returns product variant objects enriched with a metafields property.
time · string
The day of the user. This can be a unix timestamp or match any RFC time standard.
limit · string
Used to limit the number of results returned.
uuid · string
The 'Universally Unique Identifier' of the subject - the client is responsible for creating the token that represents the session. Example value: be6f5fab-32a4-43e5-967c-68017baa3aa5
url · string
A value to be searched and matched within a URL. Example: beanie-reversible
format · string
Valid values: pretty. Use pretty to make the response easy to read.
country_code · string

The ISO 3166-1 alpha-2 country code (e.g., US, CA, GB) corresponding to a Market region. Retrieves variant pricing from the Market’s catalog. The prices returned reflect the shop’s first active Market that matches the provided country_code. Only products included in that Market’s catalog will be returned in the response — products excluded from the catalog will not appear.

Required Shopify Scope: read_markets

Replaces the deprecated presentment_prices query parameter.

Code Example

// GET https://rebuyengine.com/api/v1/custom/id/{ RULESET_ID }
const params = new URLSearchParams({
  shopify_product_ids: "YOUR_VALUE",
  shopify_variant_ids: "YOUR_VALUE"
});

fetch(`https://rebuyengine.com/api/v1/custom/id/{ RULESET_ID }?${params}`)
  .then(response => response.json())
  .then(data => console.log(data));

Response Examples

200 - 200

{
  "data": [
    {
      "id": 4484974870564,
      "title": "Classic Beanie",
      "body_html": "Keep your head warm and look good doing it! Comfortable rib knitted hat in soft acrylic. Double yarn gives it a marbled look. Small folded leather logo on the side.",
      "vendor": "Example Brand",
      "product_type": "Beanie",
      "created_at": "2020-01-28T16:23:44-05:00",
      "handle": "beanie-classic",
      "updated_at": "2020-08-20T16:55:58-04:00",
      "published_at": "2020-01-28T16:23:44-05:00",
      "template_suffix": "",
      "published_scope": "web",
      "tags": "clothing",
      "admin_graphql_api_id": "gid://shopify/Product/4484974870564",
      "variants": [
        {
          "id": 31628219449380,
          "product_id": 4484974870564,
          "title": "Default Title",
          "price": "24.00",
          "sku": "BEANIE1",
          "position": 1,
          "inventory_policy": "deny",
          "compare_at_price": null,
          "fulfillment_service": "manual",
          "inventory_management": null,
          "option1": "Default Title",
          "option2": null,
          "option3": null,
          "created_at": "2020-01-28T16:23:45-05:00",
          "updated_at": "2020-08-20T16:51:01-04:00",
          "taxable": true,
          "barcode": "",
          "grams": 0,
          "image_id": null,
          "weight": 0,
          "weight_unit": "lb",
          "inventory_item_id": 33399553163300,
          "inventory_quantity": -26,
          "old_inventory_quantity": -26,
          "requires_shipping": true,
          "admin_graphql_api_id": "gid://shopify/ProductVariant/31628219449380"
        }
      ],
      "options": [
        {
          "id": 5868989841444,
          "product_id": 4484974870564,
          "name": "Title",
          "position": 1,
          "values": [
            "Default Title"
          ]
        }
      ],
      "images": [
        {
          "id": 14057549561892,
          "product_id": 4484974870564,
          "position": 1,
          "created_at": "2020-01-28T16:24:01-05:00",
          "updated_at": "2020-01-28T16:24:01-05:00",
          "alt": null,
          "width": 600,
          "height": 600,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/classic-beanie.jpg?v=1580246641",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/14057549561892"
        }
      ],
      "image": {
        "id": 14057549561892,
        "product_id": 4484974870564,
        "position": 1,
        "created_at": "2020-01-28T16:24:01-05:00",
        "updated_at": "2020-01-28T16:24:01-05:00",
        "alt": null,
        "width": 600,
        "height": 600,
        "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/classic-beanie.jpg?v=1580246641",
        "variant_ids": [],
        "admin_graphql_api_id": "gid://shopify/ProductImage/14057549561892"
      }
    },
    {
      "id": 4484976148516,
      "title": "Reversible Beanie",
      "body_html": "Classic Beanie",
      "vendor": "Example Brand",
      "product_type": "Beanie",
      "created_at": "2020-01-28T16:24:50-05:00",
      "handle": "beanie-reversible",
      "updated_at": "2020-12-17T15:09:30-05:00",
      "published_at": "2020-01-28T16:24:50-05:00",
      "template_suffix": "",
      "published_scope": "web",
      "tags": "clothing",
      "admin_graphql_api_id": "gid://shopify/Product/4484976148516",
      "variants": [
        {
          "id": 31628220530724,
          "product_id": 4484976148516,
          "title": "Default Title",
          "price": "24.00",
          "sku": "BEANIE1",
          "position": 1,
          "inventory_policy": "deny",
          "compare_at_price": null,
          "fulfillment_service": "manual",
          "inventory_management": "shopify",
          "option1": "Default Title",
          "option2": null,
          "option3": null,
          "created_at": "2020-01-28T16:24:50-05:00",
          "updated_at": "2020-12-17T15:09:30-05:00",
          "taxable": true,
          "barcode": "",
          "grams": 0,
          "image_id": null,
          "weight": 0,
          "weight_unit": "lb",
          "inventory_item_id": 33399558504484,
          "inventory_quantity": 100,
          "old_inventory_quantity": 100,
          "requires_shipping": true,
          "admin_graphql_api_id": "gid://shopify/ProductVariant/31628220530724"
        }
      ],
      "options": [
        {
          "id": 5868992036900,
          "product_id": 4484976148516,
          "name": "Title",
          "position": 1,
          "values": [
            "Default Title"
          ]
        }
      ],
      "images": [
        {
          "id": 14057553854500,
          "product_id": 4484976148516,
          "position": 1,
          "created_at": "2020-01-28T16:25:05-05:00",
          "updated_at": "2020-01-28T16:25:05-05:00",
          "alt": null,
          "width": 600,
          "height": 600,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/reversible-beanie.jpg?v=1580246705",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/14057553854500"
        }
      ],
      "image": {
        "id": 14057553854500,
        "product_id": 4484976148516,
        "position": 1,
        "created_at": "2020-01-28T16:25:05-05:00",
        "updated_at": "2020-01-28T16:25:05-05:00",
        "alt": null,
        "width": 600,
        "height": 600,
        "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/reversible-beanie.jpg?v=1580246705",
        "variant_ids": [],
        "admin_graphql_api_id": "gid://shopify/ProductImage/14057553854500"
      }
    }
  ],
  "metadata": {
    "input_products": [
      {
        "id": 562405015588,
        "title": "50/50 T - The Best T Shirt On The Market and Definitely The Best Fabric Too",
        "body_html": "50/50 T",
        "vendor": "Example Brand",
        "product_type": "",
        "created_at": "2018-03-20T14:16:12-04:00",
        "handle": "hanes-50-50-t-shirt",
        "updated_at": "2021-01-06T18:40:04-05:00",
        "published_at": "2019-09-26T22:48:25-04:00",
        "template_suffix": "",
        "published_scope": "global",
        "tags": "clothing",
        "admin_graphql_api_id": "gid://shopify/Product/562405015588",
        "variants": [
          {
            "id": 7162531512356,
            "product_id": 562405015588,
            "title": "Lime",
            "price": "8.00",
            "sku": "H5050TS-1",
            "position": 1,
            "inventory_policy": "deny",
            "compare_at_price": null,
            "fulfillment_service": "manual",
            "inventory_management": "shopify",
            "option1": "Lime",
            "option2": null,
            "option3": null,
            "created_at": "2018-03-20T14:16:12-04:00",
            "updated_at": "2021-01-06T18:36:35-05:00",
            "taxable": true,
            "barcode": "",
            "grams": 0,
            "image_id": 2155956699172,
            "weight": 0,
            "weight_unit": "lb",
            "inventory_item_id": 7159756619812,
            "inventory_quantity": 98,
            "old_inventory_quantity": 98,
            "requires_shipping": true,
            "admin_graphql_api_id": "gid://shopify/ProductVariant/7162531512356"
          },
          {
            "id": 7162531545124,
            "product_id": 562405015588,
            "title": "Yellow",
            "price": "8.00",
            "sku": "H5050TS-2",
            "position": 2,
            "inventory_policy": "continue",
            "compare_at_price": null,
            "fulfillment_service": "manual",
            "inventory_management": null,
            "option1": "Yellow",
            "option2": null,
            "option3": null,
            "created_at": "2018-03-20T14:16:12-04:00",
            "updated_at": "2020-05-01T14:33:59-04:00",
            "taxable": true,
            "barcode": "",
            "grams": 0,
            "image_id": 2155957387300,
            "weight": 0,
            "weight_unit": "lb",
            "inventory_item_id": 7159756652580,
            "inventory_quantity": -12,
            "old_inventory_quantity": -12,
            "requires_shipping": true,
            "admin_graphql_api_id": "gid://shopify/ProductVariant/7162531545124"
          }
        ],
        "options": [
          {
            "id": 833046904868,
            "product_id": 562405015588,
            "name": "Color",
            "position": 1,
            "values": [
              "Lime",
              "Yellow"
            ]
          }
        ],
        "images": [
          {
            "id": 2155956699172,
            "product_id": 562405015588,
            "position": 1,
            "created_at": "2018-03-20T14:16:17-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-lime-A.png?v=1573880386",
            "variant_ids": [
              7162531512356
            ],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155956699172"
          },
          {
            "id": 2155957157924,
            "product_id": 562405015588,
            "position": 2,
            "created_at": "2018-03-20T14:16:20-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-lime-B.png?v=1573880386",
            "variant_ids": [],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155957157924"
          },
          {
            "id": 2155957387300,
            "product_id": 562405015588,
            "position": 3,
            "created_at": "2018-03-20T14:16:22-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-yellow-A.png?v=1573880386",
            "variant_ids": [
              7162531545124
            ],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155957387300"
          },
          {
            "id": 2155957583908,
            "product_id": 562405015588,
            "position": 4,
            "created_at": "2018-03-20T14:16:25-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-yellow-B.png?v=1573880386",
            "variant_ids": [],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155957583908"
          }
        ],
        "image": {
          "id": 2155956699172,
          "product_id": 562405015588,
          "position": 1,
          "created_at": "2018-03-20T14:16:17-04:00",
          "updated_at": "2019-11-15T23:59:46-05:00",
          "alt": null,
          "width": 1528,
          "height": 1528,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-lime-A.png?v=1573880386",
          "variant_ids": [
            7162531512356
          ],
          "admin_graphql_api_id": "gid://shopify/ProductImage/2155956699172"
        }
      }
    ],
    "matched_rules": [
      {
        "logic": [
          {
            "rules": [
              {
                "type": "product",
                "operator": "contains_any",
                "value": "",
                "products": [
                  {
                    "product_id": 562407407652,
                    "variant_ids": []
                  },
                  {
                    "product_id": 562405015588,
                    "variant_ids": []
                  },
                  {
                    "product_id": 562399838244,
                    "variant_ids": []
                  }
                ]
              }
            ]
          }
        ],
        "output": [
          {
            "type": "product",
            "products": [
              {
                "product_id": 591006728228,
                "variant_ids": []
              },
              {
                "product_id": 4484974870564,
                "variant_ids": []
              },
              {
                "product_id": 4484976148516,
                "variant_ids": []
              }
            ]
          }
        ],
        "exit_if_matched": true
      }
    ],
    "unmatched_rules": [],
    "unevaluated_rules": [
      {
        "logic": [
          {
            "rules": [
              {
                "type": "cart_subtotal",
                "operator": "greater_than",
                "value": "50"
              }
            ]
          }
        ],
        "output": [
          {
            "type": "endpoint",
            "endpoint": "/products/recommended"
          }
        ],
        "exit_if_matched": true
      }
    ],
    "filtered_oos_products": [
      {
        "id": 591006728228,
        "title": "Classic Beanie",
        "body_html": "Classic Beanie",
        "vendor": "Example Brand",
        "product_type": "",
        "created_at": "2018-03-30T11:53:26-04:00",
        "handle": "classic-beanie",
        "updated_at": "2020-12-24T14:40:35-05:00",
        "published_at": "2020-01-28T16:11:45-05:00",
        "template_suffix": "",
        "published_scope": "web",
        "tags": "clothing",
        "admin_graphql_api_id": "gid://shopify/Product/591006728228",
        "variants": [
          {
            "id": 7321573425188,
            "product_id": 591006728228,
            "title": "Default Title",
            "price": "15.00",
            "sku": "BEANIE1",
            "position": 1,
            "inventory_policy": "deny",
            "compare_at_price": null,
            "fulfillment_service": "manual",
            "inventory_management": "shopify",
            "option1": "Default Title",
            "option2": null,
            "option3": null,
            "created_at": "2018-03-30T11:53:26-04:00",
            "updated_at": "2020-12-24T14:40:35-05:00",
            "taxable": true,
            "barcode": "",
            "grams": 0,
            "image_id": null,
            "weight": 0,
            "weight_unit": "lb",
            "inventory_item_id": 7334298255396,
            "inventory_quantity": 0,
            "old_inventory_quantity": 0,
            "requires_shipping": true,
            "admin_graphql_api_id": "gid://shopify/ProductVariant/7321573425188"
          }
        ],
        "options": [
          {
            "id": 872156528676,
            "product_id": 591006728228,
            "name": "Title",
            "position": 1,
            "values": [
              "Default Title"
            ]
          }
        ],
        "images": [
          {
            "id": 2245076910116,
            "product_id": 591006728228,
            "position": 1,
            "created_at": "2018-03-30T11:53:29-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1130,
            "height": 1112,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Beanie-black.png?v=1573880386",
            "variant_ids": [],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2245076910116"
          }
        ],
        "image": {
          "id": 2245076910116,
          "product_id": 591006728228,
          "position": 1,
          "created_at": "2018-03-30T11:53:29-04:00",
          "updated_at": "2019-11-15T23:59:46-05:00",
          "alt": null,
          "width": 1130,
          "height": 1112,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Beanie-black.png?v=1573880386",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/2245076910116"
        }
      }
    ],
    "filtered_input_products": [],
    "errors": []
  }
}

400 - 400

{
  "error": "Missing key"
}