Fields
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.
| Field | Type | Rule |
|---|---|---|
| store_stateoptional | string or null | Your store's own state, two letters, which a line going through your store must be allowed to reach. |
| destinationsrequired | array | Where the order's lines go: 1 to 8. |
| destinations[].keyrequired | string | Your name for it, up to 32 characters, each once in the body. |
| destinations[].kindrequired | string | dealer, the dealer the buyer chose; address, the order's shipping address; store, the buyer collects at your store; or pending, a dealer not chosen yet, so no state is checked. |
| destinations[].stateoptional | string or null | Its state, two letters. |
| linesrequired | array | The order's lines: 1 to 100. |
| lines[].keyrequired | string | Your own id for the line, up to 32 characters. It comes back unchanged. |
| lines[].product_idrequired | integer | The product_id GET /products answers with. |
| lines[].quantityrequired | integer | 1 to 9,999. |
| lines[].destinationrequired | string | The key of one of the body's destinations. One the body does not declare is 422. |
| pinsoptional | array | The distributor you chose for a line: the plan buys that line from it, choosing its route and every other line around it. Up to 100, each line at most once. |
| pins[].linerequired | string | A line's key. One the body does not send is 422. |
| pins[].distributorrequired | string | The distributor's slug, as a carrier names it. One that can no longer fill the line is ignored, and the line is planned as if not pinned. |
- 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, orvia_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 goesto_store, one leg. - The cheapest plan, not each line's cheapest offer: shipping is per box, so the plan prices whole combinations.
cheapest_itemsis each line's cheapest offer on its own, priced the same way, andsavingswhat 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_chosenwhat 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 hasif_chosenonly 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:
| Field | Meaning |
|---|---|
| quoted_at | When it was worked out. Offers and stock move: ask again before you buy. |
| lines | Each line, in the order sent, with every carrier, below. |
| plan | The cheapest way to buy the lines that can be filled, below, or null when none can. |
| cheapest_items | Each line's cheapest offer on its own, priced with shipping: the plan's totals without its boxes, or null when no line can be filled. |
| savings | What the plan saves against cheapest_items when both are fully priced, a decimal string, or null. |
| cheapest_plan | The cheapest way with no pins, its totals as in cheapest_items: the same totals as plan when you pin nothing, or null when no line can be filled. |
Each of lines | Meaning |
|---|---|
| key | As sent. |
| product_id | As sent. |
| upc | The product's UPC, or null. |
| title | The product's title, or null. |
| quantity | As sent. |
| destination | The destination's key, as you sent it. |
| parcel_destination | Where its parcel goes: the same key, except for a firearm you sent to an address, which goes on through your store to a dealer not chosen yet. That is your pending destination when you declared one, else a key the plan adds, pending_dealer (or the first free variant), of kind pending with no state. |
| shipping_class | handgun, long_gun, ammunition or other: which of a distributor's rates applies to it. |
| in_house_stock | Units you hold yourself, for information: the plan only buys from distributors. |
| status | planned: a carrier can fill it. no_carrier: none can. unknown_product: no such product. |
| carriers | Every selected distributor's offer for it, one per distributor (the offer its plan buys), cheapest first, below. |
| pin_ignored | true when you pinned this line to a distributor that can no longer fill it, so the plan chose another; else false. |
Each of carriers | Meaning |
|---|---|
| distributor | The distributor's slug, as GET /distributors lists it. |
| distributor_name | Its name. |
| cost | What you pay for one, or null when its feed sent no cost. |
| map_price | The minimum advertised price, or null. |
| stock | Units it has. |
| drop_ship | Whether this offer may be drop-shipped: allowed, blocked or unknown, which counts as allowed. |
| drop_ship_program | Whether the distributor's terms offer drop-ship at all: offered, not_offered or unknown. |
| routes | How it can reach the destination: direct, via_store or to_store. |
| refusal | Why it cannot fill the line: short_stock (fewer than the quantity), no_cost or state_restricted (it will not ship it to any state the line could go through). Null when it can. |
| planned_route | The route the plan uses it by, or null when the plan does not use it. |
| logo_url | The distributor's logo, or null when there is none. |
| if_chosen | What the order would cost with it filling the line: its route, the order's total, complete, unknown_shipments and the difference from the plan's total, negative when it costs less. The plan itself for the carrier the plan uses; null when it cannot fill the line. |
plan | Meaning |
|---|---|
| items_total | Cost times quantity, every line the plan fills. |
| distributor_shipping | Every distributor box's shipping that is published. |
| store_shipping | Every box you ship on, from FFL Monkey's estimate. |
| total | All three. |
| complete | true when every box has a published rate. |
| unknown_shipments | Boxes with no published rate, left out of the totals. |
| shipments | The boxes, below. |
Each of shipments | Meaning |
|---|---|
| kind | distributor, a distributor's box, or store, your own box on to the destination. |
| distributor | Its slug; null for a store box. |
| distributor_name | Its name; null for a store box. |
| route | Which of the shipping terms priced it: drop_ship, store or any. |
| ship_to | destination or store. |
| destination | The destination's key its lines were sent to, as you sent it; null when it goes to your store. |
| parcel_destination | Where the box goes: its lines' parcel_destination; null when it goes to your store. |
| lines | The lines in it, each its key, quantity, unit_cost and line_cost. |
| subtotal | The lines in it. |
| shipping | Its shipping, or null when the rate is not published. |
| charges | The rate and fees that make up shipping, each a label and an amount. |
| terms_source | Where the shipping terms were read, or null. |
| terms_checked_on | When they were last checked, or null. |
| logo_url | The distributor's logo, or null for a store box. |
Returns
- 200The plan, in
data. A plan nobody can fill is still200, withplannull. - 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.