REST API

Do you have an online marketplace or a retail website? Do you want to empower your customers with safe and convenient payments? Integrate with GunTab through our API.

Overview

The GunTab API is a RESTful JSON API. That means it is designed to:

This guide covers the following topics:

Authentication

API authentication is token-based.

API tokens can only be generated by users who have verified their email.

After your email has been verified, create a token from your GunTab account. Your token secret should be used in your "Authorization" header with a "Token" type, like this:

Authorization: Token 55555555-5555-5555-5555-555555555555

API token types

By default, API tokens are "test" type. This means they will return dummy responses without actually taking any action. These dummy responses are formatted exactly like live responses. Please use these test API tokens for all development and testing pursposes. For real production purposes, please generate a "live" API token.

Warning: Don't forget to use a "live" API token in your production environment. If GunTab is giving you success responses, but your requests don't otherwise seem successful, it is because you are using a "test" API token.

Errors

All errors have the same format: 

{
  "errors": [
    "Your authentication token is invalid."
  ]
}

Invoices

You can use the API to create and read Invoices. These are also known as "payment requests". An Invoice is how a seller initiates a GunTab transaction to get paid. If a buyer accepts an Invoice, GunTab will help the buyer select a local FFL and make payment.

Create Invoice

Create a new Invoice. Give the buyer_email if you want GunTab to send an email to the buyer, or leave it empty and send the response_url to the buyer your own way. Maximum per seller of 20 per hour and 100 per 24 hour period, unless you request an exception. (Marketplace users are not limited, only the sellers they represent.)

Endpoint

POST https://api.guntab.com/v1/invoices

Parameters

Response

After creating an Invoice with a buyer_email value, you can ask the buyer to check their email for a payment request from GunTab.

After creating an Invoice without a buyer_email value, you should redirect the buyer to the response_url that appears in the response payload.

Example Request JSON

{
  "counterparty_email": "buyer@example.com",
  "manual_sales_tax_amount_cents": "6375",
  "merchandise_amount_cents": "75000",
  "payment_method_convenience_fee_paid_by": "buyer",
  "seller_order_id": "555555",
  "redirect_url": "https://www.example.com/thanks-for-ordering",
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": "3500",
  "type": "Invoice",
  "workflow_state": "pending_counterparty_response",
  "listings": [
    {
      "listing_type_id": "handgun",
      "quantity": 1,
      "title": "Glock 19x Gen 5 9mm",
      "url": "https://www.gunbroker.com/item/769824133"
    }
  ]
}

Example Response JSON

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2025-05-01T05:47:42.630Z",
  "id": "dcd87b84-eaa7-4c22-b929-fca45e52dfa6",
  "live": false,
  "manual_sales_tax_amount_cents": 6375,
  "marketplace_buyer_fee_amount_cents": 0,
  "marketplace_seller_fee_amount_cents": 0,
  "merchandise_amount_cents": 75000,
  "object": "Invoice",
  "payment_method_convenience_fee_amount_cents": null,
  "payment_method_convenience_fee_paid_by": "buyer",
  "receiving_address": null,
  "receiving_ffl_license_number": null,
  "redirect_url": "https://www.example.com/thanks-for-ordering",
  "response": null,
  "response_at": null,
  "response_url": "https://www.guntab.com/purchases/dcd87b84-eaa7-4c22-b929-fca45e52dfa6/counterparty_responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_email": "seller@example.com",
  "seller_order_id": "555555",
  "service_fee_amount_cents": null,
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": 3500,
  "status": "pending_counterparty_response",
  "listings": [
    {
      "amount_cents": null,
      "description": null,
      "listing_type_id": "handgun",
      "external_id": null,
      "quantity": 1,
      "serial_number": null,
      "title": "Glock 19x Gen 5 9mm",
      "url": "https://www.gunbroker.com/item/769824133"
    }
  ]
}

Read Invoice

Get the details of an existing Invoice, including the response_url that can be shared with the buyer for checkout, and the tracking_code for the outbound_shipment after it becomes available.

Endpoint

GET https://api.guntab.com/v1/invoices/:id

Response

When using a "test" API token, this endpoint will return dummy data. The live key in the response indicates if you are using a live API token.

Example Request JSON

{}

Example Response JSON

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2025-05-01T05:47:42.630Z",
  "id": "dcd87b84-eaa7-4c22-b929-fca45e52dfa6",
  "live": false,
  "manual_sales_tax_amount_cents": 6375,
  "marketplace_buyer_fee_amount_cents": 0,
  "marketplace_seller_fee_amount_cents": 0,
  "merchandise_amount_cents": 75000,
  "object": "Invoice",
  "outbound_shipment": {
    "status": "in_transit",
    "tracking_code": "1Z879E930346834440"
  },
  "payment_method_convenience_fee_amount_cents": null,
  "payment_method_convenience_fee_paid_by": "buyer",
  "receiving_address": null,
  "receiving_ffl_license_number": null,
  "redirect_url": "https://www.example.com/thanks-for-ordering",
  "response": null,
  "response_at": null,
  "response_url": "https://www.guntab.com/purchases/dcd87b84-eaa7-4c22-b929-fca45e52dfa6/counterparty_responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_email": "seller@example.com",
  "seller_order_id": "555555",
  "service_fee_amount_cents": null,
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": 3500,
  "status": "pending_outbound_shipment_delivery",
  "listings": [
    {
      "amount_cents": null,
      "description": null,
      "listing_type_id": "handgun",
      "external_id": null,
      "quantity": 1,
      "serial_number": null,
      "title": "Glock 19x Gen 5 9mm",
      "url": "https://www.gunbroker.com/item/769824133"
    }
  ]
}

Users

You can use the API to get information about a user based on their email. The intent is to help you determine if a user has a GunTab account, and whether it is in good standing.

Warning: This is an alpha-stage endpoint which may change in the future.
For marketplace users only.

Read User

Get the details of an existing User by providing a URL-encoded email address. If no User is associated with the email, an error will be returned.

Endpoint

GET https://api.guntab.com/v1/users/EMAIL
(where EMAIL represents a URL-encoded email address)

Response

Either 200 for success or 422 for failure.

Example Request JSON

{}

Example Response JSON

{
  "active": true,
  "email": "seller@example.com",
  "live": false,
  "object": "User",
  "payment_method_convenience_fee_paid_by_default": "buyer",
  "payment_method_convenience_fee_percent": 3.0,
  "service_fee_paid_by_default": "seller",
  "service_fee_percent": 2.9
}

FFL verifications

You can use the API to call an FFL and provide your verification code. This is useful for marketplaces and other services that want assurance their users' FFL claims are authentic.

Warning: This is an alpha-stage endpoint which may change in the future.
For marketplace users only.

Call FFL to provide verification code

Trigger an automated phone call to phone number the FFL has on file with the BATF, to provide your verification code. If the FFL does not answer, we will leave a voicemail. After this, you should ask the FFL to input your verification code so you can confirm it matches.

Endpoint

POST https://api.guntab.com/v1/ffls/X-XX-XXX-XX--XXXXX/claim_verification_code_calls
(where X's represent the FFL license number)

Parameters

Response

Either 201 for success or 422 for failure.

Example Request JSON

{
  "verification_code": "55555"
}

Example Response JSON

{
  "claim_verification_code": "55555",
  "firearm_license_id": "c4c52d23-544d-40e8-9d9f-8a01cd8cdc6a",
  "firearm_license_number": "X-XX-XXX-XX--XXXXX",
  "live": false
}

Webhooks

You can use the API to create, read, and delete Webhooks. GunTab will send transaction updates to each of your Webhooks, for each of your transactions. You can use these updates to keep your own systems updated, especially your inventory and accounting systems.

Warning: These Webhooks API endpoints are deprecated, and will be removed after May, 2025. Instead, please use the Webhook endpoints page to manage your webhooks.

Create Webhook

Create a new Webhook. GunTab will begin sending transaction updates immediately.

Endpoint

POST https://api.guntab.com/v1/webhooks

Parameters

Response

Example Request JSON

{
  "url": "https://www.example.com/guntab_webhooks"
}

Example Response JSON

{
  "created_at": "2025-05-01T05:47:42.659Z",
  "id": "28bf37f8-ff6a-4760-80ec-4ac0ceb4ff7f",
  "live": false,
  "signing_secret_key": "ssk_57c14957863cb5da23836c9f19ee0476",
  "url": "https://www.example.com/guntab_webhooks",
  "warning": "THIS API ENDPOINT IS DEPRECATED"
}

Read Webhook

Get the details of an existing Webhook.

Endpoint

GET https://api.guntab.com/v1/webhooks/:id

Response

When using a "test" API token, this endpoint will return dummy data. The live key in the response indicates if you are using a live API token.

Example Request JSON

{}

Example Response JSON

{
  "created_at": "2025-05-01T05:47:42.659Z",
  "id": "28bf37f8-ff6a-4760-80ec-4ac0ceb4ff7f",
  "live": false,
  "signing_secret_key": "ssk_57c14957863cb5da23836c9f19ee0476",
  "url": "https://www.example.com/guntab_webhooks",
  "warning": "THIS API ENDPOINT IS DEPRECATED"
}

Delete Webhook

Delete an existing Webhook.

Endpoint

DELETE https://api.guntab.com/v1/webhooks/:id

Response

When using a "test" API token, this endpoint will have no effect. Returns a status of 200 when successful, without any JSON payload.

Example Request JSON

{}

Example Response JSON

{}

Support

Need help or have a question? Please see our Help Center, or you can contact support.