Skip to main content

Reflow API

Reflow has a simple API that lets you fetch your project's subscribers, users and products as JSON. It can be used both in the browser (from any origin) and in scripts when building static versions with site generators or Next.js. Note that some endpoints require authentication with an API key.

Subscriptions​

The following API endpoints will help you integrate Reflow Subscriptions in your project.

Get all Subscription Plans​

GET https://api.reflowhq.com/v2/projects/<projectid>/plans/

This API endpoint will return all active subscription plans and prices. Note that only plans that can be subscribed to will show up here. Plans that have been created but are deactivated, archived or deleted will not appear in the list.

Example​

// Print all subscription plans of the project
let plans = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/plans/"
).then((r) => r.json());
console.log(plans.data);

Get a Specific Subscription Plan​

GET https://api.reflowhq.com/v2/projects/<projectid>/plans/<planid>

This API endpoint will return the details of a single subscription plan. Both active and inactive plans can be requested with this endpoint.

Example​

// Print all subscription plans of the project
let plan = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/plans/13156819"
).then((r) => r.json());
console.log(plan);

Auth​

The following API endpoints let you retrieve data objects related to the Reflow Auth service.

Get all User Accounts​

GET https://api.reflowhq.com/v2/projects/<projectid>/users/
Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the latest 20 registered users of your project. You can modify its behavior with query parameters (all are optional):

ParameterPossible ValuesDescription
pagenumber, defaults to 1If set, will return the corresponding page number of users.
perpagenumber, min 1, max 100, defaults to 20How many users to return per page.

Examples​

# In the following examples, replace <projectid> with the id of your project
# and <api_key> with an api key string token.

# Print all of the users
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v2/projects/<projectid>/users/'

Get a Specific User Account​

GET https://api.reflowhq.com/v2/projects/<projectid>/users/<userid>
Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the user with the given id from a project.

Examples​

# Fetch the given user account
# Replace <projectid> with the id of your project, <userid> with the id of
# the user you want to fetch, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v2/projects/<projectid>/users/<userid>'

Ecommerce​

You can use the following API endpoints for integration with Reflow's Ecommerce functionality.

Get Products​

GET https://api.reflowhq.com/v2/projects/<projectid>/products/

This endpoint will return an array of products from your project. You can modify its behavior using the query parameters listed below (all are optional):

ParameterPossible ValuesDescription
pagenumber, defaults to 1If set, will return the corresponding page number of products.
perpagenumber, min 1, max 100, defaults to 20How many products to return per page.
categorynumber, the id of the categoryIf set, only returns products from the given category.
searchstring, search termsIf set, only returns products which contain the search string in the product name, description or SKU.
idsstring, comma-separated list of ids

If set, only returns products with ids included in the provided list.

Example: ?ids=1234567,4444444,878787

A maximum of 100 product ids can be passed.

order

name_asc, name_desc, price_asc, price_desc, date_asc, date_desc, custom_asc, custom_desc

Choose the display order of the products. Defaults to date_desc - products will be shown newest to oldest.

You can also perform multiple sorts by separating order clauses with commas:

Example: ?order=custom_desc,name_asc

This sorts products by using the Custom Sort number (which you enter in the product edit page), and then by name from A to Z. The result is that products with Custom Sort > 0 show before the rest.

fetch_hiddenstring, true or false

When this query parameter is set to true, the returned array will also include any products that have their Show in Store option turned off.

Because these products are not meant to be seen publicly, requests with fetch_hidden=true need to be authenticated using a Reflow API Key.

Examples​

// Print the 20 newest products
let products = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/products/"
).then((r) => r.json());
console.log(products.data);

// Print the 10 oldest products
let products = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/products/?order=date_asc&perpage=10"
).then((r) => r.json());
console.log(products.data);

// Print all the products from a category
let products = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/products/?category=123456789"
).then((r) => r.json());
console.log(products.data);

Get a Specific Product​

GET https://api.reflowhq.com/v2/projects/<projectid>/products/<product>

This endpoint will return the product with the given id or handle from a project. You can modify its behavior with query parameters (optional):

ParameterPossible ValuesDescription
fetch_hiddenstring, true or false

Settings this query param to true enables the API route to fetch products that have their Show in Store option turned off.

When it is omitted or set to false, attempting to fetch a hidden product will result in a 404 error.

Because hidden products are not meant to be seen publicly, requests with fetch_hidden=true need to be authenticated using a Reflow API Key.

Examples​

// Fetch the given product by its id and print its name
let product = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/products/366797633"
).then((r) => r.json());
console.log(product.name);

// Fetch the given product by its handle
let product = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/products/radio-clock"
).then((r) => r.json());

Update a Product​

POST https://api.reflowhq.com/v2/projects/<projectid>/products/<product>
Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

Update the existing product with the given id or handle. Add one or more of the following parameters in the request body to select which product properties to update and their new values:

ParameterPossible ValuesDescription
namestring

The new name of the product.

Must be a string between 1 and 128 characters in length.

priceinteger

The new price of the product.

The passed value must be equal to the price in the currency’s smallest unit. To set the product price to $10.00 provide a value of 1000.

For zero-decimal currencies, provide the new price without multiplying by 100. For a price of ¥500 provide 500.

inventory_typestring, either "simple" or "advanced"

Set the inventory management system for this product.

Products with inventory_type set to "simple" use a boolean in_stock property to indicate availability.

Products with inventory_type set to "advanced" use a stock_quantity property to specify the exact number of items available for purchase.

in_stockboolean, true or false

Set whether the product has items in stock and is available for purchase.

true means the product is in stock and available, false means it's out of stock.

Applicable only when the product's inventory_type is set to "simple".

stock_quantitynon-negative integer, range: [0:100,000]

Set the number of items in stock available for purchase.

Applicable only when the product's inventory_type is set to "advanced".

On success the updated product object will be returned, including all the applied changes.

Examples​

# Update the given product name and price. The price is in the smallest unit (typically cents).
# Replace <projectid> with the id of your project, <productid> with the id of the product
# you want to update, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     --header 'Content-Type: application/json' \
     -X POST --data '{"name": "The new product name", "price": 123456}' \
     'https://api.reflowhq.com/v2/projects/<projectid>/products/<productid>'

Get a Specific Category​

GET https://api.reflowhq.com/v2/projects/<projectid>/categories/<category>

This endpoint will return the category with the given id or handle from a project.

Examples​

// Fetch the given category by its handle and print its name
let category = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/categories/accessories"
).then((r) => r.json());
console.log(category.name);

Get all Categories​

GET https://api.reflowhq.com/v2/projects/<projectid>/categories/

This endpoint will return the id, name, and subcategories of all categories in your project, ordered alphabetically and nested recursively. To get the products associated with a specific category, we recommend using the category parameter of the Get products endpoint.

Examples​

// 1. Fetch all categories and print their names
let categories = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/categories"
).then((r) => r.json());
console.log(categories.map((c) => c.name));

// 2. If your project has subcategories, a bit more work is needed
let printCategoryNames = (categories) => {
  for (let c of categories) {
    console.log(c.name);
    printCategoryNames(c.subcategories);
  }
};

// 2.1 Fetch all categories and print their names recursively
let categories = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/categories"
).then((r) => r.json());
printCategoryNames(categories);

// 2.2 Fetch only a specific category and its subcategories, and print their names
let categories = await fetch(
  "https://api.reflowhq.com/v2/projects/267418190/categories?root-category=177837305"
).then((r) => r.json());
printCategoryNames(categories);

Get all Orders​

GET https://api.reflowhq.com/v2/projects/<projectid>/orders/
Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the latest 20 orders in your project. You can modify its behavior with query parameters (all are optional):

ParameterPossible ValuesDescription
pagenumber, defaults to 1If set, will return the corresponding page number of orders.
perpagenumber, min 1, max 100, defaults to 20How many orders to return per page.
payment_status

string, pending paid failed refunded

If set, only orders with this payment_status will be returned.
fulfillment_status

string, unfulfilled shipped ready_for_pickup delivered returned

If set, only orders with this fulfillment_status will be returned.

is_canceledstring, true or falseIf set, only canceled or non-canceled orders will be returned.
is_archivedstring, true or falseIf set, only archived or non-archived orders will be returned.
customer_emailstring, valid email addressOnly return orders where the customer has this email address.
created_afternumber, unix timestampIf set, only orders created after this time will be returned.
created_beforenumber, unix timestampIf set, only orders created before this time will be returned.

Examples​

# In the following examples, replace <projectid> with the id of your project
# and <api_key> with an api key string token.

# Print the 20 newest orders
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v2/projects/<projectid>/orders/'

# Print 50 orders with the fulfillment_status "shipped"
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v2/projects/<projectid>/orders/?perpage=50&fulfillment_status=shipped'

# Print orders created in the period between two dates
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v2/projects/<projectid>/orders/?created_after=1669852800&created_before=1672531200'

Get a Specific Order​

GET https://api.reflowhq.com/v2/projects/<projectid>/orders/<orderid>
Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the order with the given id from a project.

Examples​

# Fetch the given order and print its status
# Replace <projectid> with the id of your project, <orderid> with the id of
# the order you want to fetch, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v2/projects/<projectid>/orders/<orderid>'

Update an Order​

POST https://api.reflowhq.com/v2/projects/<projectid>/orders/<orderid>
Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

Update the existing order with the given id from a project. The updated property needs to be added in the request body.

ParameterPossible ValuesDescription
payment_status

string, pending paid failed refunded

The new payment_status for the order.

fulfillment_status

string, unfulfilled shipped ready_for_pickup delivered returned

The new fulfillment_status for the order.

is_canceledstring, true or false

Set the is_canceled property of the order.

is_archivedstring, true or false

Set the is_archived property of the order.

delivery_informationstring

Set the delivery_information property of the order.

On success the updated order object will be returned, including all the applied changes.

Examples​

# Update the given order fulfillment_status to "shipped".
# Replace <projectid> with the id of your project, <orderid> with the id of the order
# you want to update, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     --header 'Content-Type: application/json' \
     -X POST --data '{"fulfillment_status": "shipped"}' \
     'https://api.reflowhq.com/v2/projects/<projectid>/orders/<orderid>'

Usage with the Reflow HTML Toolkit​

If you have the Reflow JS file included in a web page, you can use a convenience wrapper that gives you direct access to the API, without having to pass the full API URL and project id:

// Fetch a product and print its name using the Reflow library.
// https://cdn.reflowhq.com/v2/toolkit.min.js has been included in the page.
let product = await Reflow.api("/products/366797633");
console.log(product.name);

// Print the 20 newest products
let product = await Reflow.api("/products/");
console.log(product.data);

This way you can retrieve your product data and build entirely custom ecommerce experiences, but still add an Add to Cart button and a Shopping Cart so that the Reflow toolkit does the heavy lifting.