openapi: 3.0.3
info:
  title: GunTab REST FFLs Invoices API
  description: The GunTab REST API allows online firearms marketplaces and retail websites to integrate safe and convenient firearms payment processing, manage invoices (payment requests), confirm and fulfill orders, validate FFLs, and receive webhook events for transaction lifecycle changes.
  version: 1.0.0
  contact:
    name: GunTab
    url: https://www.guntab.com/documentation/rest-api
  license:
    name: Proprietary
servers:
- url: https://api.guntab.com/v1
  description: Production
security:
- TokenAuth: []
tags:
- name: Invoices
  description: Payment request lifecycle management
paths:
  /invoices:
    post:
      tags:
      - Invoices
      summary: Create an invoice
      description: Creates a new GunTab invoice (payment request) for a firearms transaction.
      operationId: createInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreateRequest'
      responses:
        '201':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
  /invoices/{id}:
    get:
      tags:
      - Invoices
      summary: Read an invoice
      operationId: readInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: Invoice retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '404':
          $ref: '#/components/responses/Error'
  /invoices/{id}/cancels:
    post:
      tags:
      - Invoices
      summary: Cancel an invoice
      operationId: cancelInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: Invoice cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /invoices/{id}/platform_confirmations:
    post:
      tags:
      - Invoices
      summary: Confirm an invoice as the platform
      operationId: platformConfirmInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: Platform confirmation recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /invoices/{id}/seller_confirmations:
    post:
      tags:
      - Invoices
      summary: Confirm an invoice as the seller
      operationId: sellerConfirmInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: Seller confirmation recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /invoices/{id}/fulfillments:
    post:
      tags:
      - Invoices
      summary: Fulfill an invoice
      description: Records fulfillment with a tracking code (or pickup designation).
      operationId: fulfillInvoice
      parameters:
      - $ref: '#/components/parameters/InvoiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tracking_code:
                  type: string
                  description: Carrier tracking code (required unless pickup).
      responses:
        '200':
          description: Fulfillment recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
components:
  schemas:
    Invoice:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        merchandise_amount_cents:
          type: integer
        shipping_amount_cents:
          type: integer
        buyer_email:
          type: string
        seller_email:
          type: string
        listings:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state_code:
          type: string
        zip:
          type: string
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    InvoiceCreateRequest:
      type: object
      required:
      - merchandise_amount_cents
      - shipping_amount_cents
      - listings
      properties:
        buyer_email:
          type: string
          format: email
        buyer_email_notifications_disabled:
          type: boolean
        manual_sales_tax_amount_cents:
          type: integer
        marketplace_buyer_fee_amount_cents:
          type: integer
        marketplace_seller_fee_amount_cents:
          type: integer
        merchandise_amount_cents:
          type: integer
        payment_method_convenience_fee_paid_by:
          type: string
          enum:
          - buyer
          - seller
        platform_confirmation_required:
          type: boolean
        receiving_address:
          $ref: '#/components/schemas/Address'
        receiving_ffl_license_number:
          type: string
        redirect_url:
          type: string
          format: uri
        seller_confirmation_required:
          type: boolean
        seller_email:
          type: string
          format: email
          description: Required for marketplace integrations.
        seller_order_id:
          type: string
        service_fee_paid_by:
          type: string
          enum:
          - buyer
          - seller
          - split
        shipping_amount_cents:
          type: integer
        listings:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
    Listing:
      type: object
      required:
      - amount_cents
      - description
      - listing_type_id
      - quantity
      - title
      properties:
        amount_cents:
          type: integer
        description:
          type: string
        external_id:
          type: string
        listing_type_id:
          type: integer
        quantity:
          type: integer
        serial_number:
          type: string
        title:
          type: string
        url:
          type: string
          format: uri
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    InvoiceId:
      in: path
      name: id
      required: true
      schema:
        type: string
      description: Unique invoice identifier.
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: `Token {token_uuid}` issued to verified email users.'