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):

Parameter	Possible Values	Description
page	number, defaults to 1	If set, will return the corresponding page number of users.
perpage	number, min 1, max 100, defaults to 20	How 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):

Parameter	Possible Values	Description
page	number, defaults to 1	If set, will return the corresponding page number of products.
perpage	number, min 1, max 100, defaults to 20	How many products to return per page.
category	number, the id of the category	If set, only returns products from the given category.
search	string, search terms	If set, only returns products which contain the search string in the product `name`, `description` or `SKU`.
ids	string, 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_hidden	string, `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):

Parameter Possible Values Description

fetch_hidden

Parameter	Possible Values	Description
fetch_hidden	string, `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.

string, 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:

Parameter	Possible Values	Description
name	string	The new name of the product. Must be a string between 1 and 128 characters in length.
price	integer	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_type	string, 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_stock	boolean, `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_quantity	non-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):

Parameter	Possible Values	Description
page	number, defaults to 1	If set, will return the corresponding page number of orders.
perpage	number, min 1, max 100, defaults to 20	How 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_canceled	string, `true` or `false`	If set, only canceled or non-canceled orders will be returned.
is_archived	string, `true` or `false`	If set, only archived or non-archived orders will be returned.
customer_email	string, valid email address	Only return orders where the customer has this email address.
created_after	number, unix timestamp	If set, only orders created after this time will be returned.
created_before	number, unix timestamp	If 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.

Parameter	Possible Values	Description
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_canceled	string, `true` or `false`	Set the is_canceled property of the order.
is_archived	string, `true` or `false`	Set the is_archived property of the order.
delivery_information	string	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.

Reflow API

Subscriptions​

Get all Subscription Plans​

Example​

Get a Specific Subscription Plan​

Example​

Auth​

Get all User Accounts​

Examples​

Get a Specific User Account​

Examples​

Ecommerce​

Get Products​

Examples​

Get a Specific Product​

Examples​

Update a Product​

Examples​

Get a Specific Category​

Examples​

Get all Categories​

Examples​

Get all Orders​

Examples​

Get a Specific Order​

Examples​

Update an Order​

Examples​

Usage with the Reflow HTML Toolkit​

Subscriptions

Get all Subscription Plans

Example

Get a Specific Subscription Plan

Example

Auth

Get all User Accounts

Examples

Get a Specific User Account

Examples

Ecommerce

Get Products

Examples

Get a Specific Product

Examples

Update a Product

Examples

Get a Specific Category

Examples

Get all Categories

Examples

Get all Orders

Examples

Get a Specific Order

Examples

Update an Order

Examples

Usage with the Reflow HTML Toolkit