REC+ API Quick Guide

REC+ sites have a RESTful API available to lookup or modify data. They also support webhooks which can send API objects to you on specific events such as new.order.

Set up or request API Access via admin.

To set up an account when logged in to the Admin area, open API Accounts on the sidebar.
Set your account details and the scopes you need access to.

You will then be provided both a Public API key & Full API Access (limited by scopes) via HTTP Basic Auth over HTTPS/TLS.

Manage or view the logs of your API account any time via the same API Access area in Admin.

Public key access only gives you access to public data, such as product listings. It does not allow access to private store data such as orders, nor does it allow you to make any modifications.

To access (& modify) everything allowed by your scopes, you'll need to use HTTP Basic Auth over HTTPS with the Full API username & password.

Scopes limit the access your account has, such as if your app only needs access to Orders, you can limit your scope to only Orders.

Currently available scopes:
store_content - Manages the products, categories, etc.
content - Manages the downloads, blog_items, pages, etc.
users - Manages the users, user groups, etc.)
orders - Manages the orders, payment methods, delivery, etc.

Replace {DOMAIN} with the website domain name, as well as {API_USER} & {API_PASS} with your assigned API username & password.

Curl

# Lookup all products
curl "https://{DOMAIN}/api/v1/products" --user {API_USER}:{API_PASS}

# Lookup specific product by code
curl "https://{DOMAIN}/api/v1/products/test?identifier=code" --user {API_USER}:{API_PASS}

# Update specific product by code
curl -X POST -d @data.json "https://{DOMAIN}/api/v1/products/test?identifier=code" --user {API_USER}:{API_PASS}

# Batch update products
curl -X POST -d @data.json "https://{DOMAIN}/api/v1/products" --user {API_USER}:{API_PASS}

PHP

class REC
{
    protected static string $api_user = '{API_USER}';
    protected static string $api_pass = '{API_PASS}';
    protected static string $base = 'https://{DOMAIN}';

    public static function api(string $method, string $resource, ?array $data = null): object
    {
        $ch = curl_init(static::$base . '/api/v1' . $resource);
        curl_setopt($ch, CURLOPT_USERPWD, static::$api_user . ':' . static::$api_pass);
        curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $method = strtoupper($method);
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_THROW_ON_ERROR));
            curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        } elseif ($method !== 'GET') {
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        }
        $response = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return (object) [
            'status' => $status,
            'response' => $response ? json_decode($response, false, 512, JSON_THROW_ON_ERROR) : null,
        ];
    }
}

// Lookup all products
$products = REC::api('GET', '/products');

// Lookup specific product by code
$productCode = 'test';
$product = REC::api('GET', '/products/' . $productCode . '?identifier=code');

// Create new product
$product = REC::api('POST', '/products', [
    'products' => [[
        'code' => 'test',
        'name' => 'Test Product',
    ]],
]);

// Update specific product by code
$product = REC::api('POST', '/products/' . $productCode . '?identifier=code', [
    'name' => 'Test Product UPDATED',
]);

// Batch update products
$products = REC::api('POST', '/products?identifier=code', [
    'products' => [
        [
            'code' => 'test',
            'name' => 'Test Product',
        ],
        [
            'code' => 'test2', // or this will insert/create if code not found
            'name' => 'Test Product 2',
        ],
    ],
]);

// Delete specific product by code
$product = REC::api('DELETE', '/products/' . $productCode . '?identifier=code');

// Batch delete products
$products = REC::api('DELETE', '/products?identifier=code&ids=' . implode(',', [
    'test',
    'test2',
]));

HTTP methods indicate the type of request, e.g. to lookup a collection of objects or a specific object use GET. Creating or updating an object uses POST (PATCH also supported for updates but is treated the same as POST, both support partial updates). To remove/delete a resource use DELETE. Batch creates, updates & deletes are also supported.

By default the API returns JSON responses however it can also return XML if needed.

Use Admin > API Explorer to view live example responses on the site.

All products example JSON:

{
    "href": "\/products.json?fields=&identifier=",
    "products": [
        {
            "href": "\/products\/58663.json",
            "id": 58663,
            "name": "HOT SAUCE GIFT VOUCHER",
            "code": "Sauce-gift-voucher",
            "status": "live",
            "link": "http:\/\/rec.localhost\/HOT_SAUCE_GIFT_VOUCHER--product--58663.html",
            "image": "http:\/\/rec.localhost\/userfiles\/images\/sys\/products\/HOT_SAUCE_GIFT_VOUCHER_67999_0.jpg",
            "price": {
                "normal": "400.00",
                "special_offer": "0.00"
            }
        },
        {
            "href": "\/products\/58662.json",
            "id": 58662,
            "name": "Tubby Tom's The Squealer Hot Sauce 150g",
            "code": "Sauce-997706",
            "status": "live",
            "link": "http:\/\/rec.localhost\/Tubby_Tom039s_The_Squealer_Hot_Sauce_150g--product--58662.html",
            "image": "http:\/\/rec.localhost\/userfiles\/images\/sys\/products\/Tubby_Toms_The_Squealer_Hot_Sauce_150g_12652_0.jpg",
            "price": {
                "normal": "8.40",
                "special_offer": "0.00"
            }
        },
        {
            "href": "\/products\/58661.json",
            "id": 58661,
            "name": "Traeger Texas Spicy BBQ Sauce 16oz",
            "code": "Sauce-1105410",
            "status": "live",
            "link": "http:\/\/rec.localhost\/Traeger_Texas_Spicy_BBQ_Sauce_16oz--product--58661.html",
            "image": "http:\/\/rec.localhost\/userfiles\/images\/sys\/products\/Traeger_Texas_Spicy_BBQ_Sauce_16oz_70879jpeg.jpg",
            "price": {
                "normal": "132.00",
                "special_offer": "0.00"
            }
        }
    ],
    "count": 25,
    "total_count": 83,
    "paging": {
        "offset": 0,
        "limit": 25,
        "first_page_href": "\/products.json?fields=&identifier=&limit=25&offset=0",
        "last_page_href": "\/products.json?fields=&identifier=&limit=25&offset=75",
        "next_page_href": "\/products.json?fields=&identifier=&limit=25&offset=25",
        "previous_page_href": null
    }
}

Specific product example JSON:

{
    "href": "\/products\/58661.json",
    "id": 58661,
    "name": "Traeger Texas Spicy BBQ Sauce 16oz",
    "code": "Sauce-1105410",
    "status": "live",
    "link": "http:\/\/rec.localhost\/Traeger_Texas_Spicy_BBQ_Sauce_16oz--product--58661.html",
    "image": "http:\/\/rec.localhost\/userfiles\/images\/sys\/products\/Traeger_Texas_Spicy_BBQ_Sauce_16oz_70879jpeg.jpg",
    "price": {
        "normal": "132.00",
        "special_offer": "0.00"
    },
    "additional_images": [

    ],
    "short_desc": "",
    "desc": "<p> <\/p>\n\n<p><strong>Why we love it:<\/strong><\/p>\n\n<p>Features peppery heat that’s awesome with wings or pulled pork, and its thinner consistency makes it a great choice for marinating, too.<\/p>\n\n<p>Spicy, peppery sauce with that works as marinade or sauce<\/p>\n\n<p>Great on everything from chicken and pork to beef<\/p>\n\n<p><br \/>\n<strong>What you need to know:<\/strong><\/p>\n\n<p>1 x Traeger Texas Spicy BBQ Sauce 16oz<\/p>\n\n<p>Size: 16oz \/ 473ml<\/p>\n",
    "tax_class": 1,
    "additional_prices": [

    ],
    "categories": {
        "default": {
            "href": "\/categories\/24001.json",
            "id": 24001
        },
        "2": null,
        "3": null,
        "4": null,
        "5": null
    },
    "date_added": "2023-07-25T17:31:44",
    "date_modified_admin": "2023-07-25T18:07:10",
    "date_modified_api": null,
    "sort_order": 0,
    "custom_sort_order": {
        "featured": 0,
        "special": 0
    },
    "delivery": {
        "costs_to_zones": [

        ],
        "free_delivery": 0,
        "free_delivery_zone": 0
    },
    "manufacturer": null,
    "stock": {
        "qty": 1980,
        "options_group_use_as_stock": "",
        "pack_qty": 1,
        "alert_qty": "",
        "stop_qty": "",
        "back_in_stock_date": ""
    },
    "marketing_site_link": "",
    "hide_prices": false,
    "is_enquiry_only": false,
    "banner_text": "",
    "banner_color": "#",
    "model_3d_image_path": "",
    "model_3d_image_path_ios": "",
    "download": null,
    "additional_downloads": [

    ],
    "options": [
        {
            "id": 12347,
            "group": "Multi Pack",
            "desc": "Yes",
            "code": "",
            "price": "4.20",
            "special_price": "",
            "weight": "",
            "stock_qty": 981,
            "sort_order": 1,
            "hidden": false,
            "gtin": "",
            "cost": "",
            "sync_key": "RGe0x2",
            "group_prices": {

            },
            "group_special_prices": {

            }
        },
        {
            "id": 12348,
            "group": "Multi Pack",
            "desc": "No",
            "code": "",
            "price": "0.00",
            "special_price": "",
            "weight": "",
            "stock_qty": 999,
            "sort_order": 2,
            "hidden": false,
            "gtin": "",
            "cost": "",
            "sync_key": "Rr09B2",
            "group_prices": {

            },
            "group_special_prices": {

            }
        },
        {
            "id": 12349,
            "group": "Saver Discount",
            "desc": "Yes",
            "code": "",
            "price": "1.20",
            "special_price": "",
            "weight": "",
            "stock_qty": 1980,
            "sort_order": 3,
            "hidden": false,
            "gtin": "",
            "cost": "",
            "sync_key": "E49NjR",
            "group_prices": {

            },
            "group_special_prices": {

            }
        }
    ],
    "attributes": [

    ],
    "weight": "",
    "youtube_clip": "",
    "videos": [

    ],
    "cost_price": "",
    "is_digital": false,
    "is_addon_product": false,
    "is_discontinued": false,
    "exclude_from_api_webhook": false,
    "triggers_event_system": true,
    "special_offer_start_date": null,
    "special_offer_end_date": null,
    "meta_title": "",
    "meta_keywords": "",
    "meta_description": "",
    "exclude_from_google_base": false,
    "google_product_category": "",
    "purchase_event": null,
    "bundle": {
        "sync_stock_with_components": false,
        "sync_price_with_components": false,
        "sync_cost_with_components": false,
        "sync_weight_with_components": false,
        "is_bundle": false,
        "assembly_instructions": "",
        "assembly_bin_location": ""
    },
    "launch_date": "0000-00-00 00:00:00",
    "launch_status": "live",
    "packaging_type_id": 1,
    "tags": {
        "Design": [

        ],
        "Warnings": [

        ],
        "Colours": [

        ],
        "Season": [

        ],
        "Product Ranges": [

        ],
        "No products match this group": [

        ],
        "Forge Example": [

        ]
    },
    "associations": [

    ],
    "alternatives": [

    ],
    "addons": [

    ],
    "components": [

    ],
    "variations": [
        {
            "code": "Sauce-1105410-yes-yes",
            "prev_codes": "",
            "stock": 981,
            "cost": "",
            "options": {
                "Multi Pack": "Yes",
                "Saver Discount": "Yes"
            }
        },
        {
            "code": "Sauce-1105410-no-yes",
            "prev_codes": "",
            "stock": 999,
            "cost": "",
            "options": {
                "Multi Pack": "No",
                "Saver Discount": "Yes"
            }
        }
    ]
}

Example error response: HTTP status also reflects the error status

{
    "errors": [
        {
            "status": 404,
            "message": "Product not found"
        }
    ]
}

Specific order example JSON:

{
    "href": "\/orders\/112312.json",
    "id": 112312,
    "invoice_id": 825,
    "session_id": "s.64bf9a63f18ea5.12594747",
    "start_date": "2023-07-26T00:03:07",
    "payment_date": "2023-07-26T00:03:59",
    "payment_method": {
        "href": "\/payment-methods\/58.json",
        "id": 58,
        "name": "PayPal Express Checkout"
    },
    "payment_data": {
        "verify_sign": "",
        "payer_id": "",
        "payer_status": ""
    },
    "status": "Payment Received",
    "user": {
        "href": "\/users\/123.json",
        "id": 123,
        "full_name": "Bob Smith",
        "membership_code": "",
        "email": "bob@smithnet.co.uk",
        "billing_address": {
            "recipient_name": "Bob Smith",
            "business_name": "",
            "line_1": "12 Fake Street",
            "line_2": "",
            "town": "Worcester",
            "region": {
                "href": "\/regions\/244.json",
                "country": "United States",
                "county": "Alabama"
            },
            "post_code": "WR1 1AB",
            "tel_no": "07123456789",
            "mobile_tel_no": "",
            "fax_no": ""
        }
    },
    "delivery_address": {
        "recipient_name": "Bob Smith",
        "business_name": "",
        "line_1": "12 Fake Street",
        "line_2": "",
        "town": "Worcester",
        "region": {
            "href": "\/regions\/243.json",
            "country": "UK",
            "county": "Worcestershire"
        },
        "post_code": "WR1 1AB",
        "tel_no": "07123456789",
        "mobile_tel_no": "",
        "fax_no": ""
    },
    "tracking": {
        "medium": "direct",
        "source": "",
        "term": "",
        "using_stored_data": 0
    },
    "totals": {
        "qty": 3,
        "price": "0.00",
        "vat": "25.70",
        "weight": 0,
        "delivery": "0.00"
    },
    "lines": [
        {
            "id": 19990,
            "line_rel_id": 19988,
            "line_type": "OPTION",
            "line_desc": "Saver Discount - Yes ",
            "rel_data": {
                "option": {
                    "href": "\/options\/12349.json",
                    "id": 12349,
                    "group": "Saver Discount",
                    "desc": "Yes",
                    "code": "",
                    "product": {
                        "href": "\/products\/58661.json",
                        "id": 58661
                    }
                }
            },
            "status": "Payment Received",
            "qty": 1,
            "price": "0.00",
            "vat": "0.00",
            "vat_percentage": 20,
            "each_price_ex_vat": 0,
            "each_price_vat": 0,
            "each_price_discount_ex_vat": "0.00",
            "each_price_discount_vat": 0,
            "weight": 0
        },
        {
            "id": 19989,
            "line_rel_id": 19988,
            "line_type": "OPTION",
            "line_desc": "Multi Pack - Yes ",
            "rel_data": {
                "option": {
                    "href": "\/options\/12347.json",
                    "id": 12347,
                    "group": "Multi Pack",
                    "desc": "Yes",
                    "code": "",
                    "product": {
                        "href": "\/products\/58661.json",
                        "id": 58661
                    }
                }
            },
            "status": "Payment Received",
            "qty": 1,
            "price": "0.00",
            "vat": "0.00",
            "vat_percentage": 20,
            "each_price_ex_vat": 0,
            "each_price_vat": 0,
            "each_price_discount_ex_vat": "0.00",
            "each_price_discount_vat": 0,
            "weight": 0
        },
        {
            "id": 19988,
            "line_rel_id": 0,
            "line_type": "PRODUCT",
            "line_desc": "Traeger Texas Spicy BBQ Sauce 16oz - Sauce-1105410-yes-yes",
            "rel_data": {
                "product": {
                    "href": "\/products\/58661.json",
                    "id": 58661,
                    "name": "Traeger Texas Spicy BBQ Sauce 16oz",
                    "code": "Sauce-1105410-yes-yes"
                }
            },
            "status": "Payment Received",
            "qty": 1,
            "price": "137.40",
            "vat": "22.90",
            "vat_percentage": 20,
            "each_price_ex_vat": 114.5,
            "each_price_vat": 22.900000000000006,
            "each_price_discount_ex_vat": "0.00",
            "each_price_discount_vat": 0,
            "weight": 0
        },
        {
            "id": 19991,
            "line_rel_id": 0,
            "line_type": "PRODUCT",
            "line_desc": "Tubby Tom's The Squealer Hot Sauce 150g - Sauce-997706",
            "rel_data": {
                "product": {
                    "href": "\/products\/58662.json",
                    "id": 58662,
                    "name": "Tubby Tom's The Squealer Hot Sauce 150g",
                    "code": "Sauce-997706"
                }
            },
            "status": "Payment Received",
            "qty": 2,
            "price": "16.80",
            "vat": "2.80",
            "vat_percentage": 20,
            "each_price_ex_vat": 7,
            "each_price_vat": 1.4000000000000004,
            "each_price_discount_ex_vat": "0.00",
            "each_price_discount_vat": 0,
            "weight": 0
        },
        {
            "id": 19992,
            "line_rel_id": 0,
            "line_type": "DELIVERY",
            "line_desc": "Standard",
            "rel_data": {
                "delivery": {
                    "href": "\/delivery-methods\/1.json",
                    "id": 1,
                    "name": "Standard"
                }
            },
            "status": "Payment Received",
            "qty": 1,
            "price": "0.00",
            "vat": "0.00",
            "vat_percentage": 20,
            "each_price_ex_vat": 0,
            "each_price_vat": 0,
            "each_price_discount_ex_vat": 0,
            "each_price_discount_vat": 0,
            "weight": 0
        },
        {
            "id": 19995,
            "line_rel_id": 0,
            "line_type": "COUPON",
            "line_desc": "Gift Voucher for £400.00 - C46K13i8",
            "rel_data": {
                "coupon": {
                    "href": "\/coupons\/72.json",
                    "id": 72,
                    "name": "Gift Voucher for £400.00",
                    "code": "C46K13i8"
                }
            },
            "status": "Payment Received",
            "qty": 1,
            "price": "-154.20",
            "vat": "0.00",
            "vat_percentage": 0,
            "each_price_ex_vat": -154.2,
            "each_price_vat": 0,
            "each_price_discount_ex_vat": 0,
            "each_price_discount_vat": 0,
            "weight": 0
        }
    ],
    "is_free_delivery": false,
    "customers_order_id": "",
    "fob": "",
    "required_by_date": "",
    "purchase_order_number": "",
    "delivery_note": ""
}

We use HTTP status codes for responses (such as 200 for success, 201 for created, 204 for updated, 4XX statuses for bad requests such as 404 not found, 400 for missing requirements etc). We recommend using these in your implementation, however if your API client cannot handle these, you can surpress them to all return as 200 with suppress_response_codes=true.

Date format: ISO 8601 - Complete date plus hours, minutes and seconds YYYY-MM-DDTHH:MM:SS (Timezone is the site timezone, e.g. Europe/London)

Encoding for all responses: UTF-8

Here's a list of the API resources available under /api/v1:

Some of the above resources show identifiers supported. If not otherwise shown, ID is assumed. For those with multiple possible identifiers, these give you an alternative to lookup resources using the identifier param, e.g. products support product code based lookups with /products/{code}?identifier=code.

All collection resources support limit and offset which can be used to page through results, generally the default on lists is 25 and the max for the limit is generally 1000. See examples in the paging property of collection responses.

Also most collection resources should support the fields=* url param, which allows full data on each views to be pulled back instead of just the basic data.

The following resources also allow a diffOnly=true url param to show only changes that would be made without applying them live: downloads, options, orders, products, stock, user groups, users.

For JSON responses, there's a prettyPrint=true param which can be useful as well as a callback param for front-end JSONP support if needed.

For POST updates, we recommend sending JSON as the request body. However if you'd prefer to use form-urlencoded params the you can send the JSON in a packet param.

Need access to anything not currently available or other new API functionality? Request via a support ticket.

Webhooks react to events on the site and send to a specific endpoint.
This allows you to host your own endpoint and receive in our API objects on events such as new.order, update.order, new.user, update.user, new.product, update.product, delete.product, batch-update.product, batch-delete.product and many more available.

Webhooks send the same API objects as you’d get looking up that data from the API, e.g. new.order for order #123 would send you the JSON the same as you’d get if you were to request: /api/v1/orders/123 via the API.

Set these up via Admin > API Webhooks

Webhooks support sending directly with HTTPS but optionally can also send with HTTP Basic Auth or HTTP Bearer Auth (for JWT). Like the API itself, they also support sending as XML if required though JSON is recommended.

To accept multiple webhook events, you could add multiple webhooks with different URLs, or use a single endpoint URL and enable the "Wrap Data" option which wil send the API object wrapped in an outer object that indicates which event triggered it, e.g. {"event": "event.name", "data": {...}}

The API explorer allows you to see real API GET responses directly inside the admin of the site.

Rather than fake examples, you can preview the exact same response without writing a single line of code.

Check this out in Admin > API Explorer.

Alongside the API Explorer is a new Event Simulator.

This allows you to send real API objects from the website to your webhooks using the ApiWebHooks Hook for any given event and base input object.

E.g. {"product_id":XXX} to send a new.product or update.product event.

This saves you from needing to continuously place orders or add/update products to test your integration.

This quick overview is meant to help get you started with the API.

We also have additional documentation available here.

Please also feel free to contact us via our support tickets here.

Thanks for reading.