IronRegisterGet Started

API docs

Guide: marketplace orders (GunBroker example)

A shop sells on GunBroker, through Flxpoint or its own integration. When an order comes in, it needs to land on the POS so that:

  • the stock comes off the shelf,
  • staff see it in the register's queue,
  • and a firearm goes through the shop's normal transfer process.

This guide walks through that with POST /v1/orders.

Permissions: orders: write, plus products: read to look up SKUs.

1. Accessories and ammunition: completes on the spot

curl -X POST https://app.ironregister.com/api/v1/orders \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "external_reference": "GB-1048812233",
    "channel": "GunBroker",
    "location_id": 93,
    "lines": [ { "sku": "MAG-G19-15", "qty": 2, "unit_price_cents": 2799 } ],
    "customer": { "email": "buyer@example.com", "first_name": "Casey", "last_name": "Morgan" },
    "shipping_cents": 895,
    "shipping_address": { "name": "Casey Morgan", "line1": "12 Elm St", "city": "Dayton", "state": "OH", "postal_code": "45402", "country": "US" },
    "tax_exempt": true,
    "payment_reference": "GB-PAY-771"
  }'

What each part does:

  • external_reference is GunBroker's order number, up to 36 characters. If your job retries, or the same order is sent twice, Iron Register returns the existing order with 200 and creates nothing new. Always send it.
  • unit_price_cents is the price the buyer paid on the marketplace. Leave it out to use the POS price.
  • tax_exempt: true: GunBroker is a marketplace facilitator and collects and remits sales tax itself. Sending this stops the shop from charging tax a second time. For channels where the shop owes the tax, leave it out; Iron Register then taxes at the location's rate and the total includes it.
  • customer is matched by email, or created if new. You don't need customers: write for this.
  • Payment. The order is recorded as paid with an external payment for the full total, referenced GB-PAY-771, and completes immediately. Stock comes off location 93, and inventory.changed, order.created and sale.completed fire.

Response (abridged):

{ "status": "ok", "data": { "object": "order", "id": 5530, "number": "S93-000041", "status": "completed", "source": "api", "total_cents": 6493, "tax_cents": 0, "payments": [ { "tender": "external", "amount_cents": 6493, "reference": "GB-PAY-771" } ], "next_action": null } }

2. A firearm: held for the counter

A firearm bought on GunBroker ships to the buyer's FFL, or is picked up with a Form 4473 at the shop. Either way, the licensee has to make the disposition in person. So an order with any firearm or serialized line is saved held:

curl -X POST https://app.ironregister.com/api/v1/orders \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "external_reference": "GB-1048812240",
    "channel": "GunBroker",
    "lines": [ { "sku": "GLK-G19G5", "qty": 1, "unit_price_cents": 54900, "serial_number": "BZRW99298B" } ],
    "customer": { "email": "buyer2@example.com", "first_name": "Alex", "last_name": "Kim" },
    "fulfillment": "ship",
    "shipping_address": { "name": "Rt 8 Guns (FFL)", "line1": "400 Main St", "city": "Akron", "state": "OH", "postal_code": "44308", "country": "US", "ffl_number": "4-34-XXX-XX-XX-XXXXX" },
    "tax_exempt": true,
    "payment_reference": "GB-PAY-780"
  }'

{ "status": "ok", "data": { "object": "order", "id": 5531, "status": "held", "contains_firearms": true, "next_action": "complete_at_register", "...": "…" } }

Staff see the order in the register's held tickets. The note tells them it's already paid through GunBroker, so they take payment as External. They pick the serial number (your serial_number is shown to them as the requested unit), then complete the FFL-to-FFL shipment or the 4473.

When they finish, you get sale.completed, with status awaiting_transfer or completed, and inventory.changed.

You can't complete or void a firearm order through the API. That's deliberate, because it's a federal record.

3. Cancellations

  • Non-firearm orders: POST /v1/orders/{id}/void with a reason. Stock returns to the shelf.
  • Firearm orders: return 409 FIREARM_ORDER. Ask the shop to void them in Iron Register.

4. Tracking what happened

  • Subscribe the endpoint to order.created, sale.completed, sale.voided and sale.refunded.
  • GET /v1/orders?source=api&updated_since=… lists every API order and its current state.
  • GET /v1/orders?external_reference=GB-1048812240 finds one order by your reference.