Data Feed API

1.1Every licence can have API keys

You can create API keys for any FFL Monkey licence, whichever product it is for and whichever platform your website runs on. That includes a licence you use with our WordPress plugin: you do not need a second licence or a different plan, and your keys work alongside the plugin.

The licence's product decides what a key can reach: the permissions are listed below. The licence has to be active for a key to read or change your website's data; until then those endpoints answer 403 license_not_active. On a website running the Data Feed plugin, the plugin manages the webhook, so a key can read it but cannot change it. See Webhooks.

1.2Open API keys

Sign in to your FFL Monkey account at https://backend.fflmonkey.com/dashboard/api-keys, the account you bought your licence with, and choose API keys in the menu. Keys are made there, not in wp-admin: an up-to-date plugin has no API keys tab, and a link to the old one points to your account.

1. Your FFL Monkey account
2. API keys
3. Create API key

1.3Choose its store, name it and choose its access

Choose Create API key. A key belongs to one store: pick it under Store if your account has more than one. Give it a name you will recognise later, for example "Lightspeed POS" or "Inventory script". Then give it a permission for each area of your store, from No access, Read and, where there is something to change, Read and write. A Data Feed store's key can be given:

• In-house inventory, for the Inventory API: Read and write for anything that changes your in-house stock or prices, Read for reports and dashboards, which cannot change anything.
• Products and changes, for the Store API: Read to read your products at your prices, the category tree, the brands and product classes, and what changed.
• Pricing rules: Read to read your pricing rules and store-wide pricing settings, Read and write to create, change, reorder, delete and preview rules and to change the settings. See Rules and restrictions.
• Restrictions: Read to read your restrictions, Read and write to create, change, delete and preview them.
• Distributors: Read to see which distributors you buy from and whether your credentials were accepted, and to work out how to buy an order from them, Read and write to connect and disconnect them. A key with Read and write can also switch a distributor off, so its offers stop being priced for your store: give it only to a system you trust with that.
• Webhook: Read to see where your store's changes are sent, Read and write to set that URL, test it and remove it. A key with Read and write decides where all your store's changes go, so give it only to a system you trust with them. See Webhooks.
• Subscription: Read to see your FFL Monkey subscription, and get a link to pay from when it will not renew.

An FFL Checkout store's key can be given Webhook and Subscription too, and these two:

• FFL dealers: Read to find the licensed dealers a firearm may be sent to and check a licence. See FFL Checkout.
• FFL orders: Read to read the FFL orders you reported and the licences you uploaded, Read and write to report the dealer a buyer chose, the transfer as you run it and that it happened, and to upload the licence of a dealer the registry does not have.

A key can do only what it is given, and needs at least one permission. Create one key per system, so you can revoke one without breaking the others. A store running both products holds two licences: make a key on each.

1.4Copy it straight away

An example. A real key is ffl_sk_live_ followed by 49 letters and digits.

It is shown once. We store only a fingerprint of it, so it cannot be shown again. If you lose it, revoke it and create another.

1.5Keep it safe

1.6Then test it

Send the key in the Authorization header of every request. Keys start with ffl_sk_live_ followed by 49 letters and digits. A key belongs to one store and can only see and change that store's rows.

GET /key is the "test connection" call. Run it with your real key on your server. A key without In-house inventory tests itself with the Store API's GET /key, which any key can call and which lists its permissions.

2.1Pick your system

2.2Before you connect a tool through the API

1. Create a Read and write key for this one system, so you can revoke it without breaking others. How
2. Test the connection with GET /key from the tool you will use. See its page
3. Make sure your rows exist. An adjustment needs the row first. Create rows with PUT, the batch endpoint or the CSV upload on the In-house inventory screen.

3.1What your own systems can do

• Read your products. GET /products answers your products with your own prices, stock and availability, the same rows and prices the plugin reads. GET /categories is the tree they are filed in, and GET /changes says what changed since you last asked.
• Change how your store is priced and what it shows. Rules and restrictions explains how they work. Pricing rules and the store-wide pricing settings set your prices, and restrictions set what your store hides.
• Connect your distributors. GET /distributors lists them, PUT /distributors/{slug} connects one, and POST /sourcing-plan works out how to buy an order from them.
• Keep your in-house stock current. The Inventory API reads and changes your in-house rows from a point of sale, a spreadsheet or a script. Connect a system shows the ways in.
• Have changes sent to you. A webhook sends your store's changes to your own URL, instead of you asking for them.

3.2Before you start

1. Create a key in your FFL Monkey account, with the permissions this system needs. Create an API key
2. Read how the API works: authentication, permissions, formats and limits. Store API overview

4.1What a row does in your store

The API reads and writes the same rows as the In-house inventory screen: in wp-admin, FFLMonkey.com › Data Feed › In-house inventory, or, for a store on its own website, the licence's settings in your FFL Monkey account. Each row is one product you hold yourself, identified by its UPC, with a stock count and the price you sell it at. Anything you change here shows up on that screen, and anything changed there shows up here.

• It competes with your distributors' offers for the same product. The cheapest offer wins, and at an equal price your in-house row wins.
• Your price is published as you set it. Your pricing rules and default margin do not apply to in-house rows.
• Your restrictions still apply. A rule about the product (its category, brand, product class or UPC, or your own SKU) or about stock hides your in-house row the same way it hides a distributor's offer. Rules about a distributor or a cost range do not apply to items you own.
• A row with stock 0 is kept but not offered.
• cost_price is for your own records. It does not change what your store shows.

If you have paused updates to your store in your FFL Monkey settings, changes you make through the API are still saved, but your store does not receive them while updates are paused. When you turn updates back on, your store is brought up to date.

4.2Authentication

Send the key in the Authorization header of every request:

Authorization: Bearer ffl_sk_live_3f9a…

Keys start with ffl_sk_live_ followed by 49 letters and digits. A key belongs to one store and can only see and change that store's rows. Reading needs inventory:read, which a key given In-house inventory has; changing anything needs inventory:write, which only a key given In-house inventory: Read and write has. Create a key.

A missing, mistyped, unknown or revoked key gets 401 invalid_api_key. If your FFL Monkey subscription is suspended, cancelled or not yet active, every request but GET /key gets 403 license_not_active, with the reason. GET /key still answers, and reports the same in license.

4.3Base URL and formats

https://backend.fflmonkey.com/api/v1/inventory

• Send request bodies as JSON with Content-Type: application/json. Responses are always JSON.
• Times are ISO 8601, in UTC: 2026-10-07T15:00:00+00:00.
• Money comes back as a string with two decimals ("499.00"). You may send it as a number or a string, with at most two decimals.
• A UPC is 1 to 32 letters, digits or hyphens, exactly as you store it. Leading zeros matter: 012345678905 and 12345678905 are different rows.

4.4Rate limit

Each key may make 120 requests a minute, counted across the whole API: its Store API requests count towards the same 120. A batch request counts as one request however many rows it carries, so use the batch endpoint for anything over a handful of rows.

Every response to a valid key carries X-RateLimit-Limit and X-RateLimit-Remaining, refusals included: a 403 counts like any other request. A 404 or 405 for an address or a method the API does not have is answered before it is counted, and carries neither header. Past the limit you get 429 rate_limited with a Retry-After header giving the seconds to wait.

4.5Errors

Every error has the same shape. Branch on error; show message to a person. New codes may be added, so treat an unknown error by its HTTP status.

4.6The item

Every item response uses this shape.

4.7Endpoints

Every endpoint has a page with its fields and a documented example.

• GET/keyTest the connection
• GET/itemsList rows
• GET/items/{upc}Read one row
• PUT/items/{upc}Create or replace a row
• PATCH/items/{upc}Change some fields
• POST/items/{upc}/adjustMove stock up or down
• POST/items/batchCreate or replace many rows
• DELETE/items/{upc}Remove a row

4.8Versioning

This is version 1, and the /v1/ in the address is a promise: it only grows. We may add endpoints, response fields, optional request fields, error codes and values (such as a new source), so ignore fields you do not know and treat unknown values as valid.

We will not remove or rename a field, change its type or meaning, or make an optional field required. A change that would break that is a new version at a new address.

4.9OpenAPI document

A machine-readable description of this API (OpenAPI 3.1), for Postman, code generators and similar tools:

https://docs.fflmonkey.com/openapi/inventory-v1.json

5.1Fields

None. Any key with In-house inventory access can call it. To test a key that has only Products and changes, use the Store API's GET /key, which any key can call.

It answers even when the store's subscription is not active, and says so in license. Every other endpoint then answers 403 license_not_active, so this is the call that tells your integration why it stopped.

What it answers

Returns

• 200The calling key.

It can also answer 401 invalid_api_key, 403 product_not_included, 403 insufficient_scope (a key without In-house inventory) and 429 rate_limited. It never answers 403 license_not_active: license says why the other endpoints do.

6.1Query parameters

All optional. Needs read access.

Returns

• 200A page of rows in data, ordered by UPC, and meta with total, per_page, current_page and last_page.
• 422validation_failed: a query parameter broke a rule.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope (a key without In-house inventory) and 429 rate_limited.

Each row has the item shape.

7.1Fields

Only the UPC, in the address. Needs read access.

Returns

• 200The row, in data.
• 404item_not_found: the store has no row for that UPC.
• 422The UPC in the address is not 1 to 32 letters, digits or hyphens.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope (a key without In-house inventory) and 429 rate_limited.

8.1Fields

Needs write access. The body is the whole row.

This is a full replacement: an optional field you leave out becomes empty (null). To change one field and keep the rest, use PATCH.

Returns

• 201Created: the row is new.
• 200Replaced: the row existed.
• 422validation_failed: errors names each field.
• 403insufficient_scope: a Read only key.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included and 429 rate_limited.

9.1Fields

Needs write access. Send any of the PUT fields, with the same rules; the rest are kept. Send null to clear cost_price, sku or notes; stock and price cannot be null. An empty body is refused.

• PATCH never creates a row: 404 item_not_found if it does not exist.
• If the row's price is 0.00, include a price unless the change leaves stock at 0.

Returns

• 200Updated: the whole row, in data.
• 404item_not_found: create the row with PUT or batch first.
• 422A field broke a rule, the body was empty, or the row is priced 0.00.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included and 429 rate_limited.

10.1Fields

Needs write access. The row must already exist.

• Stock never goes below 0. A delta that would take it lower stops at 0, and the response says so with clamped and applied_delta.
• On a row priced 0.00, an adjustment that would leave stock above 0 is refused with 422 on price: set a price with PUT or PATCH first. An adjustment that takes its stock to 0 is allowed.

The adjustment in the response

The answer is the row as it now is, in data, and the adjustment beside it, in adjustment: {"data": {…}, "adjustment": {…}}.

Returns

• 200Applied, or replayed (header Idempotent-Replayed: true).
• 404item_not_found: the row must exist first.
• 409idempotency_key_reused: the key was used for a different adjustment.
• 422A field broke a rule, or the row is priced 0.00.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included and 429 rate_limited.

10.2Idempotency

PUT, PATCH and batch set absolute values, so sending one twice is harmless. An adjustment is different: if a "sold one" request times out and your system sends it again, a second -1 would take away a unit you still have.

So send an Idempotency-Key header with every adjustment: a value unique to that one event and the same on every retry of it, such as your POS sale id plus the line number. Up to 255 printable characters.

• Same key, same UPC, same delta: nothing changes. You get the original result back, with the header Idempotent-Replayed: true. data shows the row as it is now.
• Same key, different UPC or delta: 409 idempotency_key_reused, and nothing changes.
• A request that failed (for example 404 because the row did not exist yet) does not use up its key. Retry it with the same key once the cause is fixed.

Keys are per store, and are remembered for as long as the adjustment log is kept.

11.1Fields

Needs write access. The body is {"items": [...]} with 1 to 1,000 items. Each item is written exactly as PUT would.

• It counts as one request against the rate limit and refreshes your store's prices once for the whole batch, so it is the right call for a full re-count or a scheduled sync.
• Each item is checked on its own: valid items are written and invalid ones are reported, with the same error shape a single PUT would give.
• The same UPC twice in one request refuses the whole request with 422 validation_failed, and nothing is written.
• Results come back in the order you sent the items.

Returns

• 200Per-item results: created, updated, failed counts and results in request order.
• 422The whole request was refused: no items, more than 1,000, or the same UPC twice.
• 413payload_too_large: send fewer items per batch.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included and 429 rate_limited.

12.1Fields

Only the UPC, in the address. Needs write access.

To keep a row but stop offering it, set its stock to 0 instead.

Returns

• 204Removed. No body.
• 404item_not_found: there is no row for that UPC.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included and 429 rate_limited.

13.1What it reads

The Store API reads what the FFL Monkey plugin puts in a store, for a store that is not on WordPress or a system beside one: your products with your own prices, stock and availability, the category tree they are filed in, and what changed since you last asked. Where these pages say your FFL Monkey screens, such as your Pricing or Exclusions screen, they mean your store's settings: in wp-admin under FFLMonkey.com, or, for a store on its own website, the licence's settings in your FFL Monkey account. It also says what state your store is in, what it still has to set up, and how its FFL Monkey subscription stands.

• Your prices, as your plugin would show them. Each product comes with the price your pricing rules and rounding give it, the same rows and the same prices the plugin reads.
• It reads, and changes how your store is priced and what it shows: your pricing rules and restrictions, your store-wide pricing settings, the distributors you buy from, and the URL your store's changes are sent to, its webhook. To change your in-house stock and prices, use the Inventory API. It is the same API, with the same key, the same rules and the same errors, under https://backend.fflmonkey.com/api/v1/inventory.
• For an FFL Checkout store, it finds the licensed dealers a firearm may be sent to and records which one a buyer chose: FFL dealers and FFL orders.
• One key, one store. A key reaches its own store and nothing else, and does only what its permissions allow.

13.2Authentication

Send the key in the Authorization header of every request:

Authorization: Bearer ffl_sk_live_3f9a…

Keys start with ffl_sk_live_ followed by 49 letters and digits, and are made in your FFL Monkey account, on its API keys page. Create a key.

A missing, mistyped, unknown or revoked key gets 401 invalid_api_key. If your FFL Monkey subscription is suspended, cancelled or not yet active, the endpoints that read or change your store's data answer 403 license_not_active, with the reason. GET /key and GET /store still answer, and say why, and GET /subscription answers with a link to pay from.

13.3Permissions

A key has a permission per area of your store, chosen when you create it in your FFL Monkey account, under API keys: No access, Read, or, where there is something to change, Read and write. A key belongs to one store, and is offered the permissions of that store's product. Today a key can be given:

A key's permissions are also listed as scopes (products:read, pricing_rules:read, pricing_rules:write, restrictions:read, restrictions:write, distributors:read, distributors:write, inventory:read, inventory:write, webhook:read, webhook:write, dealers:read, ffl_orders:read, ffl_orders:write, subscription:read). An endpoint that needs one the key does not hold answers 403 insufficient_scope, naming it in required_scope; an endpoint of the other product answers 403 product_not_included, naming that product in required_product. GET /key and GET /store need no permission: any key may call them. More permissions are offered as their endpoints are added.

13.4Base URL and formats

https://backend.fflmonkey.com/api/v1

• Responses are always JSON, with the result in data. A list also has meta.
• Times are ISO 8601, in UTC: 2026-10-08T14:03:00+00:00.
• Send request bodies as JSON with Content-Type: application/json.
• Money comes back as a string with two decimals ("499.00"), never a number. Weights and sizes are decimal strings too. Send money as a string too ("22.50"), with at most two decimals: a JSON number is read the same, and a third decimal is refused rather than rounded.
• A product is known by its product_id, a whole number. Changes name products by it.

13.5Rate limit

Each key may make 120 requests a minute, counted across the whole API, Inventory API included. Every response to a valid key carries X-RateLimit-Limit and X-RateLimit-Remaining, refusals included, except a 404 or 405 for an address or a method the API does not have, which is answered before it is counted. Past the limit you get 429 rate_limited with a Retry-After header giving the seconds to wait.

A page of products can hold up to 500, so walking even a large catalog takes a handful of requests.

POST /webhook/test has a second limit of its own: 5 a minute for the store, whichever key calls it, because each call makes FFL Monkey send a request to your URL.

POST /pricing-rules/preview and POST /restrictions/preview share one too: 10 previews a minute for the store, the two together, whichever key calls them, because each one works part of your catalog out twice, for up to five seconds.

PUT /distributors/{slug} has its own as well: 5 a minute and 20 an hour for the store, whichever key calls it, refused ones included, because each one signs in at the distributor with your credentials, and a distributor may lock an account after repeated failed sign-ins. Disconnecting is not limited.

Each of these limits counts every request the endpoint answers, refused ones included, and on these endpoints X-RateLimit-Limit and X-RateLimit-Remaining describe whichever limit has fewer requests left, usually the endpoint's own rather than the key's 120.

13.6Errors

Every error has the same shape as the Inventory API's. Branch on error; show message to a person. New codes may be added, so treat an unknown error by its HTTP status. These codes are the Store API's own:

• 404 product_not_found: the store has no price for that product.
• 409 sync_paused: the store has switched catalog sync off, so its products are not served.
• 410 cursor_expired: a changes cursor older than the changes kept.
• 404 webhook_not_set: the store has no webhook to read, test or remove.
• 409 webhook_managed_by_plugin: the store's Data Feed plugin manages its webhook.
• 404 pricing_rule_not_found and 404 restriction_not_found: the store has no pricing rule, or no restriction, with that id.
• 422 zero_match_confirmation_required: a pricing rule or restriction that matches no product was not saved, until you confirm it.
• 422 catalogue_wipe_confirmation_required: a restriction that would empty your store was not saved, until you confirm it.
• 404 distributor_not_found: no distributor has that slug.
• 422 credentials_rejected and 502 distributor_unreachable: the distributor refused the credentials, or did not answer the check, so nothing was saved.

13.7The product

Every product the Store API answers with has this shape: the catalog's description of it, and your own price, stock and availability.

13.8Keep a copy of your catalog current

For a website or a point of sale that keeps its own copy of your products:

1. Read every product you sell with GET /products, a page at a time, and keep the meta.changes_cursor of the first page.
2. Call GET /changes with that cursor. Apply each change, then save meta.next_cursor and call again from it. Every answer has one, even when nothing changed.
3. When meta.has_more is true, call again straight away; otherwise, a few minutes later.

A change is applied as it comes: its payload is the state after the change, never a difference, and applying one twice is harmless. Changes are kept for at least 30 days. A cursor older than that answers 410 cursor_expired: start again from step 1.

13.9When catalog sync is switched off

A store can switch catalog sync off in its FFL Monkey screens. While it is off, GET /products and GET /products/{id} answer 409 sync_paused instead of a page: it is not an empty catalog, so keep what you have. GET /categories still answers, and GET /changes leaves out product, price and in-house inventory changes, which are not replayed later. Once GET /products answers again, read your products again.

13.10Have changes sent to you

Instead of asking GET /changes every few minutes, a store can have each change sent to its own URL as it happens. A store has one webhook URL, set with PUT /webhook; a store whose Data Feed plugin is connected already has its webhook. Each delivery is signed, so your receiver can check it came from FFL Monkey. How webhooks work, and how to check the signature.

13.11Change how your store is priced and what it shows

A Data Feed store's pricing rules and restrictions, the ones on its Pricing and Exclusions screens, can be read and written with the API, with the same checks and the same consequences as a save on those screens. A rule or restriction names categories, brands and product classes by the slugs GET /categories, GET /manufacturers and GET /product-classes list. Your store-wide pricing settings go with them: the default margin, for a product no rule matches, and the price rounding and MAP floor that finish every price. PATCH /pricing-settings changes them. How rules and restrictions work, and the saves you confirm.

13.12Connect your distributors

A Data Feed store's distributors, the ones on its distributors screen, can be listed, connected and disconnected with the API. GET /distributors lists every distributor FFL Monkey offers, whether your store buys from it, and in credential_fields what it takes to connect it.

• Credentials are checked with the distributor before anything is saved. PUT /distributors/{slug} signs in at the distributor with them, and only if it accepts them saves them and switches it on. A refused check (422 credentials_rejected) or one the distributor does not answer (502 distributor_unreachable) saves nothing.
• They are never returned, in any answer, change or webhook: only whether they were accepted, and when.
• Turning one off forgets its credentials. DELETE /distributors/{slug} switches it off and deletes them.
• 5 connects a minute and 20 an hour per store, because a distributor may lock an account after repeated failed sign-ins.
• Buying an order from them. POST /sourcing-plan takes an order's lines and where each goes, and answers every distributor carrying each line and the cheapest way to buy the lot with shipping, the plan your Data Feed order screen shows.

13.13FFL Checkout: dealers and orders

An FFL Checkout store that sells firearms on a website of its own can do what the FFL Checkout plugin does at checkout: find the licensed dealer (an FFL) a firearm ships to, and record which one the buyer chose.

• Find a dealer. GET /dealers/search is the search FFL Monkey's own dealer picker runs: by a ZIP or a point, nearest first, or by name or licence number. It finds only active dealers a firearm may be transferred to, and gives each one's coordinates for your own map.
• Check one licence. GET /dealers/{licenseNumber} says whether a licence is real and current, in any form of its number. Keep a dealer's license_key: it stays the same when the licence is renewed.
• Report the order. POST /ffl-orders records the dealer the buyer chose, by your own order number, and POST /ffl-orders/{ref}/complete that the transfer happened, which puts the dealer on file with your store. Both are safe to repeat. These two keep the dealer, never the buyer.
• Report the transfer. POST /ffl-orders/{ref}/transfer keeps the transfer as your system runs it, from the request to the dealer to the parcel received, sent whole after every change, so it shows in your FFL Monkey screens beside the order. It keeps the buyer's details you send in it.
• A dealer the registry does not have. Send the licence the buyer gave you with POST /ffl-contributions; FFL Monkey reads and approves it, and GET /ffl-contributions/{contribution} then answers the dealer's licence number.
• Dealer searches share your checkout's limits: 120 a minute from one address and 5,000 a day for the store, counted with your store's dealer picker. A lookup of one dealer by licence number is outside the daily limit.

13.14Endpoints

Every endpoint has a page with its fields and a documented example.

• GET/keyTest the connection
• GET/storeRead the store
• GET/productsList products
• GET/products/{id}Read one product
• GET/categoriesList categories
• GET/manufacturersList brands
• GET/product-classesList product classes
• GET/changesRead what changed
• GET/webhookRead the webhook
• PUT/webhookSet the webhook URL
• POST/webhook/testSend a test event
• DELETE/webhookRemove the webhook
• GET/subscriptionRead the subscription
• GET/pricing-rulesList pricing rules
• GET/pricing-rules/{id}Read one pricing rule
• POST/pricing-rulesCreate a pricing rule
• PATCH/pricing-rules/{id}Change a pricing rule
• DELETE/pricing-rules/{id}Delete a pricing rule
• POST/pricing-rules/reorderReorder pricing rules
• POST/pricing-rules/previewPreview a pricing rule
• GET/pricing-settingsRead the pricing settings
• PATCH/pricing-settingsChange the pricing settings
• GET/restrictionsList restrictions
• GET/restrictions/{id}Read one restriction
• POST/restrictionsCreate a restriction
• PATCH/restrictions/{id}Change a restriction
• DELETE/restrictions/{id}Delete a restriction
• POST/restrictions/previewPreview a restriction
• GET/distributorsList distributors
• PUT/distributors/{slug}Connect a distributor
• DELETE/distributors/{slug}Disconnect a distributor
• POST/sourcing-planWork out how to buy an order
• GET/dealers/searchFind FFL dealers
• GET/dealers/{licenseNumber}Check one FFL licence
• POST/ffl-ordersReport the dealer a buyer chose
• POST/ffl-orders/{ref}/transferReport the order's FFL transfer
• POST/ffl-orders/{ref}/completeReport that the transfer happened
• GET/ffl-orders/{ref}Read one FFL order
• POST/ffl-contributionsUpload a dealer's licence
• GET/ffl-contributions/{contribution}Read what became of an upload

13.15Versioning

This is version 1, and the /v1/ in the address is a promise: it only grows. We may add endpoints, response fields, optional request fields, error codes, permissions and values (such as a new setup step or a new kind of change), so ignore fields you do not know and treat unknown values as valid.

We will not remove or rename a field, change its type or meaning, or make an optional field required. A change that would break that is a new version at a new address.

13.16OpenAPI document

A machine-readable description of the Store API (OpenAPI 3.1), for Postman, code generators and similar tools:

https://docs.fflmonkey.com/openapi/v1.json

The Inventory API has its own, linked from its overview.

14.1Pricing rules: the first match wins

Your rules are checked in order, lowest sort_order first, and on a tie the older rule. For each product, the first enabled rule that matches it sets its markup, and no other rule is applied: rules never add up. A product no rule matches is priced at cost plus your default margin, if one is set, and otherwise at cost: one of your store-wide pricing settings, with the price rounding and the MAP floor.

• A rule matches when every condition it has matches, and a condition matches when any one of its values does: categories (each takes in the ones below it), brands, product classes, distributors and UPCs, then the cost range and the MAP and MSRP gates. An empty condition matches anything.
• The price is the base the rule names (apply_markup_price_to), plus markup_percentage of it, plus markup_value_fixed, rounded to the cent and never below zero. Each offer is priced on its own, and the cheapest one your restrictions allow is the one your store sells, after your MAP floor and price rounding.
• Your own stock is never priced by rules. An in-house row sells at the price you set on it.
• So a rule's place is part of what it means. Put a narrow rule above a general one, or the general one takes its products. A new rule goes directly above the first rule broader than it, and POST /pricing-rules/reorder sets the whole order.

14.2Restrictions: any one of them hides

• Inside one restriction, every condition must match, and inside one condition any of its values will do. Categories handguns and rifles with the brand glock match Glock handguns and Glock rifles, and nothing else.
• Any switched-on exclude that matches hides it. One is enough, and order never matters, so restrictions have no reorder.
• Only-shows work the other way round. Once your store has a switched-on only_show, a product must match at least one of them to be shown. An exclude wins over an only-show.
• They judge each offer, not the product. A product hidden at one distributor can still be sold from another that no restriction matches. A restriction that names distributors or a cost range never hides your own stock.
• min_stock turns with the kind: on an exclude it matches an offer with fewer than that many in stock, on an only-show one with at least that many, so both hide low stock.
• A switched-off restriction (disabled) is kept, and hides nothing.

14.3Saves you confirm

Some saves are held back with a 422 until you say you mean them. Nothing is saved: send the same body again with the field the answer names.

The empty-store question comes first, so a first only-show that matches nothing needs both. Take the token from the answer rather than writing it into your code. An only-show with no condition is not confirmed but refused, since it would restrict nothing.

14.4Slugs and money

• Conditions name rows by slug. categories, manufacturers and product_classes take the slugs GET /categories, GET /manufacturers and GET /product-classes list; distributors takes distributor slugs, as a product's sourced_from names them.
• A slug that names nothing is refused by its place (manufacturers.1) and never dropped: a dropped slug would widen the rule. Slugs are checked once every other field passes, so a body with a field error and an unknown slug is told about the field first; then every slug that names nothing is named at once.
• A row deleted since a rule was saved reads "(deleted)". The rule still holds it and matches nothing through it. Sending "(deleted)" back is refused: leave that condition out of a PATCH to keep it, or send the slugs you mean.
• Money is a decimal string. Send at most two decimals, best as a string such as "22.50"; a JSON number is read the same, and a third decimal is refused, never rounded. It comes back as a string with two decimals.

14.5Preview before you save

POST /pricing-rules/preview and POST /restrictions/preview take the body you would save, or an id and the fields you would change, and say what saving it would do: how many products it names, and up to 25 real products worked out both ways. They write nothing. Your store may make 10 previews a minute, the two kinds together, whichever key asks.

14.6What a save sets off

• Your store is worked out again, exactly as after a change on your FFL Monkey screens. New prices, and products leaving or coming back, arrive as merchant_price.recomputed changes.
• The save itself is announced as pricing_rule.created, .updated, .deleted or .reordered, or restriction.created, .updated or .deleted: to your webhook, and in GET /changes for a key that can read them.
• A create is not idempotent. A create retried after a lost answer makes a copy: list them, and delete the copy.

15.1Set it

A store has one webhook URL. Set it with PUT /webhook, using a key with Webhook: Read and write, which a key of a Data Feed or an FFL Checkout store can hold.

• The secret is shown once, in the answer to the PUT that created the webhook. It signs every delivery. Changing the URL keeps it; for a new one, DELETE /webhook and set the URL again.
• Test it before you rely on it with POST /webhook/test, which sends one signed webhook.tested event and tells you what your URL answered.
• A store whose Data Feed plugin is connected already has its webhook. The plugin set it up and receives every change, so PUT /webhook answers 409 webhook_managed_by_plugin. GET /webhook shows it, with managed_by plugin.
• A webhook is optional. Reading GET /changes every few minutes works as well.

15.2What is sent

Your store's own changes, never another store's, and the same for every key: a key that sets the URL decides where all of them go. For a Data Feed store:

For an FFL Checkout store: its FFL orders (ffl_selection.*, ffl_order.*), and its licence and subscription, as above.

Each change is the object GET /changes returns, and its payload is the state after the change. New kinds of change may appear: ignore a type you do not know. A kind added later reaches a webhook already set, without setting it again.

15.3Each delivery

A POST to your URL with a JSON body {"events": [change]}, one change per request. It carries these headers:

15.4Check the signature

Before you trust a delivery, prove it came from FFL Monkey:

1. Read the body raw, exactly as it arrived, before any JSON parsing.
2. Join X-FFL-Timestamp, a dot and the raw body, and compute its HMAC-SHA256 with your secret, in hex. Put sha256= in front.
3. Compare that with X-FFL-Signature using a constant-time comparison, never ==.
4. Refuse a timestamp more than 5 minutes from your clock, so an old delivery cannot be sent to you again.

Answer a delivery that fails the check with 401, and never apply it. The code column has the check in each language.

15.5Apply each change once

• By event_id. The same change can arrive twice, after a retry, and a change you already read with GET /changes can arrive later by webhook. Keep the event_ids you applied, and answer 200 to one you have seen.
• Never go back. Changes can arrive out of order. Skip one whose cursor is not above the last one you applied for the same aggregate_type and aggregate_id. A merchant_price.recomputed change is a batch: its aggregate_id names the batch, and payload.products holds many products. Keep the last cursor you applied per product_id, and skip a product in it whose last applied cursor is above the change's.

15.6Retries and the pause

Answer any 2xx within 10 seconds, once the change is stored. Anything else is a failure: another status (4xx counts the same as 5xx), a redirect, or no answer in time. A failed delivery is tried again after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours, seven attempts in all.

• Degraded: after the first failure, GET /webhook says degraded. New changes are still sent, and the first 2xx makes it active again.
• Paused: after 50 failures in a row, it pauses, with paused_reason delivery_health. Nothing is sent, and changes made while it is paused are not kept for it.
• To resume it, fix the endpoint, then send PUT /webhook again, while your subscription is active. Then read GET /changes from your last cursor to catch up on what was not sent.
• A webhook paused for any other reason, such as billing, is not the API's to lift.

15.7When your subscription is ending

Seven days or fewer before a subscription that is set to end, your webhook gets a subscription.ending_soon change, once for each end date. Its payload holds license_id, billing_status, ends_at and cancel_at_period_end.

It carries no link. Call GET /subscription when a person is about to renew: its renewal_url works for an hour and opens your store's billing, so treat it as a secret and never store, log or email it.

16.1The error envelope

New codes may be added, so treat an unknown error by its HTTP status.

Every error answer, in this envelope or not, also carries the header X-FFL-Error-Reference, such as BE-7K3QX9PM. Log it with the error, and quote it when you write to us from Support in your FFL Monkey account or at [email protected]: it lets us find your request.

16.2Every error code

16.3Retrying safely

• 429: wait the number of seconds in Retry-After, then send the same request again. To write many rows, use POST /items/batch: it counts as one request.
• 500: retry; if it keeps happening, write to us from Support in your FFL Monkey account, or at [email protected].
• Adjustments: retry with the same Idempotency-Key, so a retry can never take away a unit twice. See Idempotency.
• PUT, PATCH and batch set absolute values, so sending one twice is harmless.

17.1Query parameters

All optional. Needs Products and changes: Read. Send at most one of cursor, ids and upc.

• Everything you sell, a page at a time. Without ids or upc you get what you sell now, ordered by product_id. Call again with cursor set to meta.next_cursor until meta.has_more is false.
• Particular products. With ids or upc you get exactly those, including ones you no longer sell, with is_visible false: that is how you learn to take one off sale. One the store has no price for is left out.
• Two of cursor, ids and upc together are refused with 422, and so is an id or a UPC that is not one.

What it answers

data is a list of products, each in the product shape, and meta says where the walk is:

Returns

• 200A page of products in data, and meta.
• 409sync_paused: the store has switched catalog sync off. Not an empty catalog: keep what you have and retry later.
• 422validation_failed: a query parameter broke a rule.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

18.1Fields

Only the product_id, in the address. Needs Products and changes: Read.

You get the product whether or not you sell it now: is_visible false means take it off sale. Use it when a change names a product, or GET /products?ids= for several at once.

Returns

• 200The product, in data, in the product shape.
• 404product_not_found: the store has no price for it, so it is not in your catalog.
• 404not_found: the id in the address is not a number.
• 409sync_paused: the store has switched catalog sync off.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

19.1Fields

None. Needs Products and changes: Read.

Every category, in one flat list ordered so that a parent always comes before its children (by depth, then sort_order), so you can build the tree in one pass. A product's category and category_path are slugs from here. It is the same tree for every store, and it is served even while catalog sync is switched off.

Each category

Returns

• 200The tree, in data.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

20.1Query parameters

All optional. Needs Products and changes: Read.

• Active brands, a page at a time. There are thousands, so call again with cursor set to meta.next_cursor until meta.has_more is false. They come in byte order of the slug.
• The slug is the brand's name in this API. Pricing rules and restrictions name brands by it, in manufacturers. A product's manufacturer shows the name.
• A brand merged into another is left out, and a rule or restriction that sends its slug is refused. One saved before the merge still reads back with that slug: to change its brands, send the slug of the brand it was merged into, or leave manufacturers out of a PATCH to keep what it holds.
• FFL Monkey staff can change a slug; the brand stays the same brand. Read the list again rather than keeping it for good.
• The same for every store, and served while catalog sync is switched off.

Each brand

Where the walk is

Returns

• 200A page of brands in data, and meta.
• 422validation_failed: a query parameter broke a rule.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

21.1Fields

None. Needs Products and changes: Read.

Every product class, by slug, in one short list, in the order your FFL Monkey screens show them. A product's product_class is one of these slugs, and pricing rules and restrictions name classes by it, in product_classes. It is the same list for every store, and it is served while catalog sync is switched off.

Each class

Returns

• 200Every class, in data.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

22.1Query parameters

All optional. Needs Products and changes: Read.

1. Read your products with GET /products and keep the meta.changes_cursor of its first page.
2. Call GET /changes?cursor= with it. Apply each change, then call again with meta.next_cursor. Every answer has one, even when nothing changed, and it moves on past changes that are not for your key, so save it each time.
3. When meta.has_more is true, call again straight away; otherwise, a few minutes later.

Each change

Exactly what a webhook delivery carries. Apply each once, by event_id; reading one twice is harmless.

The changes your key gets

You never get another store's changes. If your store switches catalog sync off, product, price and in-house inventory changes are left out while it is off, and are not replayed later, and meta.sync_paused is true. Once it is false again, read your products again. To have changes sent to you instead of asking for them, set a webhook.

What it answers

Returns

• 200The changes after the cursor, oldest first, in data, and meta.
• 410cursor_expired: changes are kept for at least 30 days, and this cursor is older than what is kept. Read GET /products again and carry on from its meta.changes_cursor.
• 422validation_failed: a query parameter broke a rule.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

23.1Fields

None. Needs Pricing rules: Read, a permission of Data Feed stores.

Your pricing rules, the ones on your Pricing screen, first checked first. For each product, the first enabled rule that matches it sets its price, and no other rule is applied; a product no rule matches is priced at cost plus your default margin, if one is set. How rules and restrictions work together: Rules and restrictions.

Each rule

A rule matches a product when every condition it has matches, and a condition matches when any one of its values does. Money is a string with two decimals.

Returns

• 200Every rule, in data, in the order they are checked.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

24.1Fields

Only the rule's id, in the address. Needs Pricing rules: Read.

One rule, in the shape GET /pricing-rules lists it, conditions by slug. Use it when a pricing_rule.* change names a rule: the change's payload names categories, brands and classes by internal ids, which this API never shows.

Returns

• 200The rule, in data.
• 404pricing_rule_not_found: your store has no rule with that id. Another store's rule is the same answer.
• 404not_found: the id in the address is not a number.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

25.1Fields

Needs Pricing rules: Read and write. Send the rule's fields as GET /pricing-rules shows them, without id and sort_order. A field left out is null, false or an empty list.

Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. A rule's place is not a field: sort_order is refused. Move a rule with POST /pricing-rules/reorder.

• Where it goes. With auto_place (the default) it goes directly above the first rule that is broader than it, as your Pricing screen places a new rule, so a narrow rule is checked before a general one. false puts it last. To choose another place, reorder afterwards.
• Slugs are checked, not guessed. A slug that names nothing, or a brand merged into another, is 422 validation_failed, named by its place, such as manufacturers.1. It is never dropped: a dropped slug would widen the rule. Slugs are checked once every other field passes, so fix the fields errors names first; then every slug that names nothing is named at once.
• What follows: exactly what follows a rule saved on the Pricing screen. Your prices are worked out again and arrive as merchant_price.recomputed changes, and the rule is announced as pricing_rule.created.

Returns

• 201Created: the rule, in data, with its id and sort_order.
• 422validation_failed: a field broke a rule. errors names each one.
• 422zero_match_confirmation_required: the rule matches no product. Nothing was saved.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

26.1Fields

The rule's id in the address, and in the body only the fields to change, at least one. Needs Pricing rules: Read and write.

Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. A rule's place is not a field: sort_order is refused, and so is auto_place. Move a rule with POST /pricing-rules/reorder.

• Everything you do not send is kept: the rule's place, its switch, its MAP floor setting and every condition you leave out. A condition you send replaces the old one, and [] means any.
• There is no PUT, on purpose: a PUT resets what it is not sent, so one that left out a condition would widen the rule to every product, and one that left out its place would move it.
• A condition that reads "(deleted)" cannot be sent back. Leave it out to keep what the rule holds, or send the slugs you mean.
• Its place is not a field. Move it with POST /pricing-rules/reorder.
• A change that leaves the rule matching nothing is held back as a create is, until you send "acknowledge_zero_match": true. It is asked again on each later change while the rule still matches nothing.
• What follows: your prices are worked out again, and the rule is announced as pricing_rule.updated.

Returns

• 200The rule as it is now, in data.
• 404pricing_rule_not_found: your store has no rule with that id.
• 422validation_failed: a field broke a rule, or the body has none of the rule's fields (named body).
• 422zero_match_confirmation_required: the rule would match no product. Nothing was changed.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

27.1Fields

Only the rule's id, in the address. Needs Pricing rules: Read and write.

The products the rule priced fall to the next rule that matches them, or to your default margin. Your prices are worked out again, and the rule is announced as pricing_rule.deleted. To keep a rule but stop applying it, PATCH it with "disabled": true instead.

Returns

• 204Deleted. No body.
• 404pricing_rule_not_found: your store has no rule with that id.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

28.1Fields

Needs Pricing rules: Read and write.

• The whole list, every time. A list that leaves a rule out, names one twice or names one your store does not have is 422 validation_failed on ordered_ids, and nothing moves.
• Every price is worked out again, since any rule may now be the first to match a product, and the change is announced as pricing_rule.reordered.
• To move one rule, read the list, move its id, and send the list back.

Returns

• 200Every rule, in data, in the new order.
• 422validation_failed: the list is not every rule, each once.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

29.1Fields

Needs Pricing rules: Read and write, like the save it stands in for. It is the preview your Pricing screen shows, and it saves nothing: no rule, no price and no change are written or announced. Send one of two bodies:

• A new rule: the body you would send to POST /pricing-rules, checked as a create is. It is previewed where that create would put it.
• A change to a rule: rule_id and the fields you would send to PATCH /pricing-rules/{id}, laid over the rule as the PATCH would lay them. rule_id alone previews the rule as it is.

Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. A rule's place is not a field: sort_order is refused. Move a rule with POST /pricing-rules/reorder.

10 previews a minute per store, pricing rules and restrictions together, whichever key asks, on top of the key's own limit: each one works part of your catalog out twice, for up to five seconds.

What it answers

How many products the rule names, and up to 25 real products worked out both ways, those that would change first.

Each sample

Each side, before and after

Returns

• 200What saving it would do, in data. Nothing was saved.
• 404pricing_rule_not_found: your store has no rule with that rule_id.
• 422validation_failed: a field broke a rule, as it would on the save.
• 429rate_limited: more than 10 previews in a minute for this store. Wait for Retry-After seconds.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

30.1Fields

None. Needs Pricing rules: Read, a permission of Data Feed stores.

The three store-wide settings every price is built with, beside your pricing rules: the card above the rules on your Pricing screen. They come under Pricing rules because they are the rules' fallback and finish, not a permission of their own. When one changes, here or on the screen, GET /changes and your webhook carry pricing_settings.updated with all three.

What it answers

How a price is built

1. The markup. A product no enabled rule matches is its cost plus default_margin, rounded to the cent. A product a rule matches is marked up by the rule instead.
2. The rounding of price_rounding, on every price.
3. The MAP floor, last, so rounding can never leave a price under MAP. It only ever raises a price.

Worked through for an offer no rule matches, costing 100.00 with a MAP of 119.00: "25" makes it 125.00, "0.99" makes that 125.99, which is above MAP, so the price is 125.99. With a margin of "10" it would be 110.00, then 110.99, and the floor would raise it to 119.00.

Returns

• 200The settings, in data.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

31.1Fields

Only the settings to change, at least one. Needs Pricing rules: Read and write. What each setting does: GET /pricing-settings.

• Everything you do not send is kept.
• All or nothing. Every setting sent is checked before any is saved, so a 422 validation_failed changes nothing. A body with none of the three is refused, named body.
• Money as decimal strings. The answer gives each setting back as the decimal string it is saved as, never as a number.
• What follows: exactly what follows a change on your Pricing screen. Each setting that changes is announced as pricing_settings.updated, carrying all three as GET /pricing-settings answers them, in GET /changes for a key with Pricing rules and to your webhook, and your whole catalogue is worked out again, the new prices arriving as merchant_price.recomputed changes. A setting sent with the value it already has changes nothing and is not announced.

Returns

• 200All three settings as they are now, in data.
• 422validation_failed: a setting broke a rule, or the body has none of the three (named body). Nothing was saved.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

32.1Fields

None. Needs Restrictions: Read, a permission of Data Feed stores.

Your restrictions, the rules on your Exclusions screen, oldest first. A product is hidden from your store when any switched-on exclude matches it, or when you have a switched-on only_show and none of them matches it. An exclude wins over an only-show, and order never matters, so restrictions have no reorder. How they combine, offer by offer: Rules and restrictions.

Each restriction

A restriction matches an offer when every condition it has matches, and a condition matches when any one of its values does. Money is a string with two decimals. A category, brand or product class deleted since the restriction was saved reads "(deleted)", as on a pricing rule, and sending it back is refused.

Returns

• 200Every restriction, in data, oldest first.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

33.1Fields

Only the restriction's id, in the address. Needs Restrictions: Read.

One restriction, in the shape GET /restrictions lists it, conditions by slug. Use it when a restriction.* change names one: the change's payload names categories, brands and classes by internal ids, which this API never shows.

Returns

• 200The restriction, in data.
• 404restriction_not_found: your store has no restriction with that id. Another store's is the same answer.
• 404not_found: the id in the address is not a number.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

34.1Fields

Needs Restrictions: Read and write. Send the restriction's fields as GET /restrictions shows them, without id. A field left out is null, false or an empty list.

Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. Name distributors in distributors: distributor_slug and distributor_slugs are refused.

• Checked, not guessed. A slug that names nothing is 422 validation_failed, named by its place, as on a pricing rule; so is a to_price below from_price, and a UPC or SKU that can never match.
• An only-show with no condition is refused (422 validation_failed, on categories): it would match every product and restrict nothing.
• What follows: exactly what follows a restriction saved on your Exclusions screen. Your store is worked out again (products leave or come back as merchant_price.recomputed changes), and the restriction is announced as restriction.created.

Returns

• 201Created: the restriction, in data, with its id.
• 422validation_failed: a field broke a rule. errors names each one.
• 422catalogue_wipe_confirmation_required: it would empty your store. Nothing was saved.
• 422zero_match_confirmation_required: it matches no product. Nothing was saved.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

35.1Fields

The restriction's id in the address, and in the body only the fields to change, at least one. Needs Restrictions: Read and write.

Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. Name distributors in distributors: distributor_slug and distributor_slugs are refused.

• Everything you do not send is kept: its switch, its distributors and every condition you leave out. A condition you send replaces the old one, and [] means any. There is no PUT, for the reason a pricing rule has none.
• A condition that reads "(deleted)" cannot be sent back. Leave it out to keep what the restriction holds, or send the slugs you mean.
• The checks a create meets are made on the restriction as it would be saved. Emptying the one condition of an only-show is refused, and switching on an exclude with no condition asks for its confirm_token. A change to a restriction that already matches nothing is asked about again.
• What follows: your store is worked out again, and the restriction is announced as restriction.updated.

Returns

• 200The restriction as it is now, in data.
• 404restriction_not_found: your store has no restriction with that id.
• 422validation_failed: a field broke a rule, or the body has none of the restriction's fields (named body).
• 422catalogue_wipe_confirmation_required or zero_match_confirmation_required: as on a create. Nothing was changed.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

36.1Fields

Only the restriction's id, in the address. Needs Restrictions: Read and write.

The products it hid come back, unless another restriction hides them. Your store is worked out again, and the restriction is announced as restriction.deleted. To keep a restriction but stop it hiding anything, PATCH it with "disabled": true instead.

Returns

• 204Deleted. No body.
• 404restriction_not_found: your store has no restriction with that id.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

37.1Fields

Needs Restrictions: Read and write, like the save it stands in for. It saves nothing: no restriction, no price and no change are written or announced. Send one of two bodies:

• A new restriction: the body you would send to POST /restrictions, checked as a create is. An only-show with no condition, or a from_price above the to_price, is refused, as a save refuses it.
• A change to a restriction: restriction_id and the fields you would send to PATCH /restrictions/{id}, laid over it as the PATCH would lay them.

Each list takes at most 1,000 entries. Money with a third decimal is refused, never rounded. Name distributors in distributors: distributor_slug and distributor_slugs are refused.

The two confirmations a save asks for are not asked here: the preview is how you find out what they are about. 10 previews a minute per store, pricing rules and restrictions together, whichever key asks.

What it answers

The shape of a pricing rule preview, without this_rule: there applied_rule_id is the pricing rule that prices the product. A product it would hide has visible false and hidden_reason restricted after. For an only-show, what it hides is everything it does not name, so catalog_count against scope_count is the number to read, and the samples are drawn from the whole catalog as well.

Returns

• 200What saving it would do, in data. Nothing was saved.
• 404restriction_not_found: your store has no restriction with that restriction_id.
• 422validation_failed: a field broke a rule, as it would on the save.
• 429rate_limited: more than 10 previews in a minute for this store. Wait for Retry-After seconds.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

38.1Fields

None. Needs Distributors: Read, a permission of Data Feed stores.

Every distributor FFL Monkey offers, by name, and your store's connection to each, as your distributors screen shows them. It never shows a credential, nor any part of one: only whether yours are saved, and whether the distributor accepted them.

Each distributor

What to send to connect one

Each entry of credential_fields is one value PUT /distributors/{slug} needs. Distributors ask for different things, so build the form from this list rather than assuming an email and a password.

Returns

• 200Every distributor, in data, by name.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

39.1Fields

The distributor's slug in the address, from GET /distributors, and your own credentials with it in the body. Needs Distributors: Read and write, a permission of Data Feed stores.

• Checked with the distributor before anything is saved. FFL Monkey signs in at the distributor with them, which can take up to 15 seconds. Only if it accepts them are they saved and the distributor switched on (enabled true).
• A refused or unreachable check saves nothing. Nor does a field that is missing or blank, which is refused before the distributor is asked anything. Credentials saved before are kept when a new set is refused.
• Never returned. No answer, change or webhook carries a credential, nor any part of one: the answer says only that they are verified, and when.
• Connected already? Sending it again checks the new credentials and replaces the old ones.
• What follows: exactly what follows a connect on your distributors screen. Saving the credentials is announced as distributor_account.connected; switching the distributor on, as license.distributor_selection.changed, and your products and prices are worked out again.

Returns

• 200Connected: the distributor as GET /distributors now shows it, in data, with credentials verified.
• 404distributor_not_found: no distributor FFL Monkey offers has that slug.
• 422validation_failed: a credential is missing or blank, named as credentials.<key>; or credentials itself when the body has none at all, or when the distributor's credential_fields is empty, as it cannot be connected through the API yet. The distributor was not asked.
• 422credentials_rejected: the distributor did not accept them. Nothing was saved.
• 429rate_limited: more than 5 in a minute, or 20 in an hour, for this store. Wait for Retry-After seconds.
• 502distributor_unreachable: the distributor did not answer the check. Nothing was saved. The credentials may be right: try again in a few minutes.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

40.1Fields

Only the distributor's slug, in the address. Needs Distributors: Read and write.

Switches the distributor off, so its offers stop being priced for your store, and forgets your credentials for it: to turn it back on, connect it again with PUT /distributors/{slug} and send them again. It answers 204 whether or not there was anything to switch off or forget, so it is safe to repeat, and a distributor FFL Monkey no longer offers can still be disconnected. It asks the distributor nothing, so it is not limited.

Announced as distributor_account.disconnected when credentials were deleted, and license.distributor_selection.changed when the distributor was on, in which case your products and prices are worked out again, as on your distributors screen.

Returns

• 204Disconnected. No body.
• 404distributor_not_found: no distributor has that slug.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

41.1Fields

Needs Distributors: Read. The body is the order: where its lines go, and the lines. Nothing is written, and the plan is worked out afresh on every call, so ask again just before you buy.

• Priced at what you pay: each offer's cost, not your price, and each distributor's published shipping terms, a box at a time. Lines one distributor sends to one place travel in one box.
• Two ways to send a line: direct, drop-shipped by the distributor, or via_store, to your store and on from there, with both legs priced: the distributor's box to you and your own box on, from FFL Monkey's estimate of a store's shipping. A line for a buyer collecting at your store goes to_store, one leg.
• The cheapest plan, not each line's cheapest offer: shipping is per box, so the plan prices whole combinations. cheapest_items is each line's cheapest offer on its own, priced the same way, and savings what the plan saves against it.
• Every selected distributor is listed for each line, in stock or not, once. One that cannot fill it says why in refusal. The plan weighs every offer, because a distributor can list a product under two SKUs that ship differently; it lists the offer its plan buys.
• What another distributor would cost: each carrier that can fill a line says in if_chosen what the order would cost with that distributor, every other line kept with its distributor and every offer and route chosen again. Pin every line that way and the plan you get is that one, while costs and stock hold. An order too large to price every alternative has if_chosen only on the carriers the plan uses.
• A pin that cannot be kept is set aside: when the distributor you pinned can no longer fill the line, the plan buys it elsewhere and the line says pin_ignored.

What it answers

data is the plan:

Returns

• 200The plan, in data. A plan nobody can fill is still 200, with plan null.
• 422validation_failed: the body broke a rule, a line naming an undeclared destination or a pin naming a line not sent included.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

42.1Fields

None. Any key can call it, whatever its permissions, so it is the call to make first with a new key.

It answers even when the store's subscription is not active, and says so in license. The endpoints that read your store's data then answer 403 license_not_active, so this is the call that tells your integration why it stopped.

What it answers

Returns

• 200The calling key.

It can also answer 401 invalid_api_key and 429 rate_limited. It never answers 403: any key may call it, in any licence status.

43.1Fields

None. Any key can call it, whatever its permissions, and it answers whatever the subscription's status. Use it to show a person what their store still has to set up.

What it answers

Each setup step

Returns

• 200The key's store.

It can also answer 401 invalid_api_key and 429 rate_limited. It never answers 403: any key may call it, in any licence status.

44.1Fields

None. Needs Subscription: Read, which a key of a Data Feed or an FFL Checkout store can hold.

It answers whatever the subscription's status, including while the store is suspended or canceled: that is when a store most needs the link to renew. Nothing here changes the subscription.

What it answers

The plan

Told before it ends

Seven days or fewer before a subscription that is set to end, your store gets a subscription.ending_soon change, once for each end date: by webhook, and in GET /changes for a key that can also read Products and changes. Its payload holds license_id, billing_status, ends_at and cancel_at_period_end, and no link: call GET /subscription when a person is about to renew. A subscription that renews is never announced.

Returns

• 200The store's subscription, in data.

This endpoint can also answer 401 invalid_api_key, 403 insufficient_scope and 429 rate_limited. It never answers 403 license_not_active.

45.1Fields

None. Needs Webhook: Read, which a key of a Data Feed or an FFL Checkout store can hold.

A store has one webhook, whoever set it. managed_by says who: api for one set with PUT /webhook, plugin for the one the store's FFL Monkey Data Feed plugin set up when it connected. You can read the plugin's, but the API does not change, remove or test it. The secret is never shown here. How deliveries work is on Webhooks.

What it answers

Returns

• 200The store's webhook, in data.
• 404webhook_not_set: the store has no webhook. Set one with PUT /webhook.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

46.1Fields

Needs Webhook: Read and write, which a key of a Data Feed or an FFL Checkout store can hold. A Data Feed store's webhook is sent its products, prices, rules, restrictions, distributors and in-house inventory; an FFL Checkout store's, its FFL orders. Both are sent the licence's and the subscription's changes.

• One webhook URL per store. Your store's changes are sent there as they happen, so you do not have to poll GET /changes. Which changes, and what each delivery carries: Webhooks.
• The first time it answers 201, with the webhook and its secret, which signs every delivery. The secret is shown once. Store it with your receiver. If you lose it, DELETE /webhook and set the URL again for a new one.
• After that it answers 200: the URL changes, and the secret stays the one you hold.
• Give the final address. Deliveries do not follow redirects, so a URL that answers 3xx fails.
• A PUT resumes a paused webhook whose paused_reason is delivery_health, once you have fixed the endpoint, and clears its failures. Changes made while it was paused were not queued for it: read GET /changes from your last cursor to catch up.
• A key with this permission decides where all of your store's changes go, whatever else it may do. Give it only to a system you trust with them.

Returns

• 201Created: the store had no webhook. data is the webhook, as GET /webhook answers it, plus its secret, shown this once.
• 200Changed: the webhook was set with the API before. No secret.
• 409webhook_managed_by_plugin: the store's plugin manages its webhook.
• 422validation_failed: the URL broke a rule. errors.url says which.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

47.1Fields

None. Needs Webhook: Read and write.

It sends one test event to your webhook URL now, signed and with the same headers as every delivery, so a receiver that accepts it accepts the real ones (see Check the signature). The event:

• event_type is webhook.tested, and cursor is 0.
• payload holds your license_id and the url it was sent to.
• It is not one of your store's changes: it never appears in GET /changes, it is not retried, and a failed test does not count towards pausing the webhook. A test that arrives does not lift a pause either.

A paused webhook can be tested too, to check a fix before the PUT that resumes it. 5 tests a minute per store, whichever key sends them, on top of the key's own limit.

What it answers

Always 200 once something was tried: whether the test arrived is the answer.

Returns

• 200The test was tried. data.delivered says whether it arrived.
• 404webhook_not_set: the store has no webhook to test.
• 409webhook_managed_by_plugin: the store's plugin manages its webhook.
• 429rate_limited: more than 5 tests in a minute for this store. Wait for Retry-After seconds.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

48.1Fields

None. Needs Webhook: Read and write.

Removes a webhook set with PUT /webhook. Deliveries still waiting to be sent are dropped. GET /changes keeps working without a webhook. To get a new secret, remove the webhook and set it again.

Returns

• 204Removed. No body.
• 404webhook_not_set: the store has no webhook.
• 409webhook_managed_by_plugin: the store's plugin manages its webhook, and the API does not remove it.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.