FFL Checkout 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.1What your own systems can do

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.

2.2Before you start

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

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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.

3.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

3.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.

3.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.

4.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.

4.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.

4.3Each delivery

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

4.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.

4.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.

4.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.

4.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.

5.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.

5.2Every error code

5.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.

6.1Query parameters

Needs FFL dealers: Read, a permission of FFL Checkout stores. Say where with a zip or a point (latitude and longitude), never both, or which with a name or a license_number. At least one of them is required.

• The search FFL Monkey's dealer picker runs, with its rules. Only dealers whose licence is current (active, and expiring today or later, UTC) and of a type a firearm may be transferred to are found, and only those the registry could place on a map.
• By a ZIP or a point, nearest first, within radius_m. A ZIP the registry cannot place answers no dealers with meta.zip_known false: "we do not know that ZIP", not "nobody near it".
• By name or licence number, measured from the ZIP or point when you send one too, nearest first, otherwise by name. radius_m and only_on_file are for a ZIP or a point only.
• sot_only and verified_only filter before limit, on every kind of search, so the dealers they leave are still the nearest ones.
• Caps are refused, never cut down: a radius_m over 321869 or a limit over 100 is 422.
• Searches share your checkout's limits: 120 a minute from one address, across every key and dealer picker searching from it, and 5,000 a day for the store. A search by license_number with limit=1 is outside the daily limit.

What it answers

data is a list of dealers, meta says what was searched, and map names the map FFL Monkey's dealer picker draws, its style and the tiles it falls back to, so a map you draw on the results can use the same ones. Each dealer:

A page with a Content Security Policy must allow the tile host in img-src, and, to draw the style, its host in connect-src and what MapLibre itself needs (blob: workers and images).

Returns

• 200The dealers found in data, nearest first when there is an origin, with meta and map. No dealer is still a 200.
• 422validation_failed: no ZIP, point, name or licence number; a ZIP and a point together; or a parameter that 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.

7.1Fields

Only the licence number, in the address. Needs FFL dealers: Read, a permission of FFL Checkout stores.

• Any form of the number finds it: printed (1-62-037-01-3F-01187), composed, without separators, in any case, or the license_key a search answered with.
• Whatever its status. The newest registry row for the licence answers, so "expired" and "taken out of searches" are answers, not a 404. A licence a store uploaded that is still waiting for FFL Monkey's approval, or was rejected, is never answered.
• Before you ship, check transfer_eligible and verification.current: a search only ever finds dealers for whom both are true, but a number a buyer typed may not be one.
• It counts towards the 120 searches a minute from one address that your store's dealer picker counts towards too, and not towards the store's daily search limit.

What it answers

data is the licence in full: a dealer in the search's shape, with licensee_name always sent and distance_meters always null, plus:

Returns

• 200The licence, in data.
• 404dealer_not_found: the registry has no dealer for this number, in any form, or only an upload still pending or rejected.
• 404not_found: the address holds something that is not 5 to 32 letters, digits and hyphens.

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

8.1Fields

Needs FFL orders: Read and write, a permission of FFL Checkout stores. An FFL order is one fact about one of your orders: the dealer the buyer chose, and later whether the transfer happened. Your own system keeps the order.

• The first report answers 201 and is announced as ffl_selection.captured.
• Safe to repeat. The same ref again answers 200: the dealer is refreshed (the buyer may have changed it before the order settled), the status is kept, and nothing is announced again.
• A dealer the registry does not know is recorded all the same, with dealer_resolved false.
• Then report the transfer with POST /ffl-orders/{ref}/complete, which puts the dealer on file with your store.

What it answers

data is the order, the shape the three FFL order endpoints answer with:

Returns

• 201Reported: the order, in data.
• 200Reported already: the order, its dealer refreshed.
• 422validation_failed: a ref that is not an order number, a WooCommerce order key, or a field that 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.

9.1Fields

Needs FFL orders: Read and write, a permission of FFL Checkout stores. The order number goes in the address: the one you reported the order with, so the transfer joins it. It may also come first. The body is the whole transfer as it stands, sent after every change, the way FFL Monkey's checkout plugin reports the transfers it runs.

• Safe to repeat. The state is replaced by what you send, and only events with new ids are added.
• The buyer is merged field by field. A field you leave out, an empty state or country, or a value WooCommerce anonymised (such as [deleted] or [email protected]) keeps what FFL Monkey holds, and any other value, an empty one included, replaces it. To remove a buyer's details, contact [email protected].
• Buyer details are kept for the transfer record, shown in your FFL Monkey screens and to FFL Monkey's staff. Nothing about a transfer is sent to a webhook.
• An accepted event by the dealer teaches FFL Monkey's registry that the dealer takes transfers.
• The order number in the address follows the same rules as a reported ref. The body is checked first.

What it answers

data is the transfer as kept, never the buyer details it holds:

Returns

• 200Kept: the transfer as it now stands, in data.
• 422validation_failed: the body broke a rule, or the order number in the address is not one, or is a WooCommerce order key.

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

10.1Fields

Only the order number, in the address: the ref you reported the order with. Needs FFL orders: Read and write, a permission of FFL Checkout stores.

• Send it once the transfer has happened. The order is marked completed and announced as ffl_order.completed, and its dealer is then on file with your store: later searches say on_file true.
• Safe to repeat. An order completed already is answered as it is, and nothing is announced again.
• An order never reported is created, completed: the report may have been lost. It has no dealer then.
• The order number in the path follows the same rules as a reported ref: up to 64 letters, digits, dots, underscores, colons and hyphens, never a WooCommerce order key.

Returns

• 200The order, completed, in data, in the FFL order shape.
• 422validation_failed: the order number in the path is not one, or is a WooCommerce order key.

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

11.1Fields

Only the order number, in the address. Needs FFL orders: Read, a permission of FFL Checkout stores.

The order as FFL Monkey recorded it, by the order number you reported it with, or by the reference your FFL Monkey checkout plugin made for an order it reported (wc- and 32 hex characters).

Returns

• 200The order, in data, in the FFL order shape.
• 404ffl_order_not_found: your store has no FFL order with this number. Another store's order is the same answer as none.
• 422validation_failed: the order number in the path is not one, or is a WooCommerce order key.

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

12.1Fields

Needs FFL orders: Read and write, a permission of FFL Checkout stores. For a buyer whose dealer the registry does not have: send the scan of the dealer's licence the buyer gave your checkout, from your server, as multipart/form-data.

• Read, then approved. FFL Monkey reads the file and approves it, by itself or by its staff, the same way it does an upload made in its own checkout picker. Ask GET /ffl-contributions/{contribution} what became of it: once approved it answers the dealer's licence number, to report the order and its transfer with.
• 6 uploads a minute for your store, whichever key sends them, the same budget as your checkout picker's, refused ones included.

What it answers

Returns

• 202Taken, and queued to be read, in data.
• 422validation_failed: no file, a file of another type or over 10 MB, or a kind it does not know.
• 429rate_limited: more than 6 uploads in a minute for your store.

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

13.1Fields

Only the upload's id, in the address: the one POST /ffl-contributions answered with. Needs FFL orders: Read, a permission of FFL Checkout stores.

Ask again every few minutes until it is decided: FFL Monkey's checkout plugin asks every 15. Never the reading itself or the file.

What it answers

Returns

• 200The upload, in data.
• 404ffl_contribution_not_found: your store has no upload with this id. Another store's upload is the same answer as none.

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

14.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.

15.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.

16.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.

17.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.

18.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.

19.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.

20.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.