Podium Invoice API

openapi: 3.2.0
info:
  title: Payments Invoice API
  version: 2021.04.01
servers:
- url: https://api.podium.com
  variables: {}
security: []
tags:
- name: Invoice
paths:
  /v4/invoices:
    get:
      callbacks: {}
      description: 'List of all invoices that match the query parameters.


        Required scope: `read_payments`.'
      operationId: invoice.index
      parameters:
      - description: Podium unique identifier for location.
        in: query
        name: locationUid
        required: false
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      - description: Return invoices with a payment whose `createdAt` is greater or equal to this date.
        in: query
        name: datePaid
        required: false
        schema:
          description: Date time in Coordinated Universal Time (UTC).
          example: '2015-01-23T23:50:07Z'
          format: date-time
          type: string
      - description: Return invoices with a refund whose `createdAt` is greater or equal to this date.
        in: query
        name: dateRefunded
        required: false
        schema:
          description: Date time in Coordinated Universal Time (UTC).
          example: '2015-01-23T23:50:07Z'
          format: date-time
          type: string
      - description: Return invoices whose `createdAt` is greater or equal to this date.
        in: query
        name: dateCreated
        required: false
        schema:
          description: Date time in Coordinated Universal Time (UTC).
          example: '2015-01-23T23:50:07Z'
          format: date-time
          type: string
      - description: Max number of items to return per request. Defaults to `10`.
        in: query
        name: limit
        required: false
        schema:
          default: 10
          example: 10
          maximum: 100
          minimum: 0
          type: integer
      - description: Retrieves the page of items that comes after or before the `cursor`.
        in: query
        name: cursor
        required: false
        schema:
          description: Cursor used to access next or previous page in pagination.
          example: MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/invoice'
                    type: array
                  metadata:
                    description: Additional response data.
                    properties:
                      nextCursor:
                        description: Cursor to get next set of items.
                        example: MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw
                        type: string
                      previousCursor:
                        description: Cursor to get previous set of items.
                        example: MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw
                        type: string
                      totalItems:
                        description: Total number of items available.
                        type: integer
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Get all invoices.
      tags:
      - Invoice
    post:
      callbacks: {}
      description: 'Creates an invoice which is either a `card_present` or a `card_not_present` invoice.

        Providing the `reader_uid` property will create a `card_present` invoice, but if no `reader_uid`

        is provided a `card_not_present` invoice will be created.



        ### Card Present Invoice


        A card-present-invoice is used to process an invoice through a card reader. After the invoice

        is created, there is a callback to the card reader to complete the transaction. If no

        `accountUid` is given, the card reader''s default account is used.


        ### Card Not Present Invoice


        A card-not-present-invoice is used to process an invoice asynchronously. After the invoice is

        created, a payment link is sent to the customer from the merchants Podium account. The customer

        can click on the link to complete the transaction. If no `accountUid` is given, the most

        recently created account is used.


        Required scope: `write_payments`.

        '
      operationId: invoice.create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                accountUid:
                  description: Podium unique identifier for bank account.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                allowedPaymentOptions:
                  description: Restrict allowed payment options to the ones provided.
                  items:
                    enum:
                    - bankAccount
                    - creditCard
                    - debitCard
                    - buyNowPayLaterAffirm
                    type: string
                  type: array
                channelIdentifier:
                  description: Identifies the Messenger channel. Must be a valid email address or a phone number. Non-US/Canada numbers must include the country code (e.g. +61 for AUS)
                  example: email@email.com
                  type: string
                customerName:
                  description: Name of the customer who will receive the invoice.
                  example: Barry Grape
                  type: string
                invoiceNumber:
                  description: An identifier that can be used as reference ID from an external system.
                  example: abc-12345-def
                  type: string
                lineItems:
                  items:
                    description: Separate items or services that make up an invoice.
                    properties:
                      amount:
                        description: Amount to be charged for the line item, represented in cents.
                        example: 4186
                        maximum: 99999900
                        type: integer
                      description:
                        default: Total
                        description: Description of the item or service being charged.
                        example: Oil change.
                        maxLength: 50
                        type: string
                    required:
                    - amount
                    type: object
                  maxItems: 10
                  minItems: 1
                  type: array
                locationUid:
                  description: Podium unique identifier for location.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                readerUid:
                  description: Podium unique identifier for card reader.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
              required:
              - channelIdentifier
              - customerName
              - invoiceNumber
              - lineItems
              - locationUid
              type: object
        description: Create invoice params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/invoice'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Create an invoice.
      tags:
      - Invoice
  /v4/invoices/{uid}:
    get:
      callbacks: {}
      description: 'Gets an invoice that has previously been created.


        Required scope: `read_payments`.'
      operationId: invoice.get
      parameters:
      - description: Podium unique identifier for invoice.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      - description: Podium unique identifier for location.
        in: query
        name: locationUid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/invoice'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Get an invoice.
      tags:
      - Invoice
  /v4/invoices/{uid}/cancel:
    post:
      callbacks: {}
      description: 'Cancels an invoice. The seller cannot collect payments for the canceled invoice.


        Required scope: `write_payments`.'
      operationId: invoice.cancel
      parameters:
      - description: Podium unique identifier for invoice.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                locationUid:
                  description: Podium unique identifier for location.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                note:
                  description: Internal note left as to why it was canceled.
                  example: Voided invoice.
                  type: string
              required:
              - locationUid
              - note
              type: object
        description: Invoice cancel params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/invoice'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Cancel an invoice.
      tags:
      - Invoice
  /v4/invoices/{uid}/charge:
    post:
      callbacks: {}
      description: 'Charges an existing invoice using keyed-in payment details from a Stripe payment method ID.


        Required scope: `write_payments`.'
      operationId: invoice.charge
      parameters:
      - description: Podium unique identifier for invoice.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                idempotencyUid:
                  description: Optional idempotency identifier to make retries safe.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                locationUid:
                  description: Podium unique identifier for location.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                paymentMethodId:
                  description: Stripe payment method id.
                  example: pm_1GTWhCELrVx5KpCHKXoM6XSj
                  type: string
                shouldSaveCardOnFile:
                  default: false
                  description: Whether the card should be saved for future off-session charges.
                  type: boolean
              required:
              - locationUid
              - paymentMethodId
              type: object
        description: Invoice charge params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/invoice'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Charge an invoice.
      tags:
      - Invoice
  /v4/invoices/{uid}/refund:
    post:
      callbacks: {}
      description: 'Refunds an invoice. The invoice must currently have a `status` of `paid`.If an invoice has a `status` of `created` it cannot be refunded, but can be canceled. An invoice can have multiple refunds. The total refunded amount cannot exceed the invoice''s `amount`.


        Required scope: `write_payments`.'
      operationId: invoice.refund
      parameters:
      - description: Podium unique identifier for invoice.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: Amount to refund on the invoice, represented in cents.
                  example: 4186
                  minimum: 1
                  type: integer
                locationUid:
                  description: Podium unique identifier for location.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                note:
                  description: Detailed note for why the refund was initiated.
                  example: incorrect amount
                  type: string
                paymentUid:
                  description: Podium unique identifier for payment.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
                reason:
                  description: Generic reason for why the refund was initiated.
                  enum:
                  - accidental_charge
                  - canceled
                  - duplicate
                  - fraudulent
                  - requested_by_customer
                  type: string
              required:
              - amount
              - locationUid
              - paymentUid
              - reason
              type: object
        description: Invoice refund params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/invoice'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Refund an invoice
      tags:
      - Invoice
  /v4/invoices/{uid}/setup:
    post:
      callbacks: {}
      description: 'Creates a setup intent so clients can tokenize card details with Stripe.js and obtain a `paymentMethodId` for manual entry charging.


        Required scope: `write_payments`.'
      operationId: invoice.setup
      parameters:
      - description: Podium unique identifier for invoice.
        in: path
        name: uid
        required: true
        schema:
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                locationUid:
                  description: Podium unique identifier for location.
                  example: 00000000-0000-0000-0000-000000000000
                  format: uuid
                  type: string
              required:
              - locationUid
              type: object
        description: Invoice setup params
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/invoice'
                  metadata:
                    description: Additional response data.
                    properties:
                      url:
                        description: The resource URL.
                        example: https://www.podium.com/
                        type: string
                    type: object
                type: object
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: Podium code for the error.
                    type: integer
                  message:
                    description: Specific details about the error.
                    type:
                    - string
                    - 'null'
                  moreInfo:
                    description: URL providing more information about the error.
                    type: string
                title: Error
                type: object
          description: Error response.
      summary: Create invoice setup intent.
      tags:
      - Invoice
components:
  schemas:
    invoice:
      description: Payment invoice.
      properties:
        allowedPaymentMethods:
          items:
            description: List all the payment methods available for the invoice.
            example:
            - Bank Account
            - Buy Now Pay Later Affirm
            - Credit Card
            - Debit Dard
            type:
            - string
            - 'null'
          type: array
        amount:
          description: The amount of the invoice.
          example: 2000
          type:
          - integer
          - 'null'
        canceledAt:
          description: If the invoice has been canceled this will be set to when it was canceled.
          example: '2015-01-23T23:50:07Z'
          format: date-time
          type:
          - string
          - 'null'
        canceledNote:
          description: If the invoice has been canceled this will be an internal note left as to why it was canceled.
          example: The wrong amount was entered.
          type:
          - string
          - 'null'
        channel:
          description: Channel that the invoice payment request was sent through.
          properties:
            identifier:
              description: Identifies the Messenger channel. Must be a valid email address or a phone number. Non-US/Canada numbers must include the country code (e.g. +61 for AUS)
              example: email@email.com
              type:
              - string
              - 'null'
            type:
              description: Messenger channel for the conversation.
              enum:
              - apple
              - car_wars
              - email
              - facebook
              - fallback_email
              - google
              - google_brand
              - iframe
              - instagram
              - phone
              - secure
              - sms
              - text
              - whatsapp
              example: email
              type:
              - string
              - 'null'
          type: object
        conversationUid:
          description: Podium unique identifier for conversation.
          example: 00000000-0000-0000-0000-000000000000
          format: uuid
          type:
          - string
          - 'null'
        createdAt:
          description: When the invoice was created.
          example: '2015-01-23T23:50:07Z'
          format: date-time
          type:
          - string
          - 'null'
        currencyRef:
          description: The currency the invoice was sent in.
          example: USD
          type:
          - string
          - 'null'
        customerName:
          description: Name of the customer who received the invoice.
          example: Joe Orange
          type:
          - string
          - 'null'
        invoiceNumber:
          description: An identifier that can be added manually by a user or as reference ID from an external system.
          example: abc-12345-def
          type:
          - string
          - 'null'
        invoiceServiceChargeItems:
          items:
            description: Separate taxes or service charges applied to an invoice.
            properties:
              amount:
                description: Amount charged for the tax or service charge, represented in cents.
                example: 1099
                type: integer
              flatChargeAmount:
                description: Flat charge amount, represented in cents. Null if PERCENTAGE_BASED
                example: 1099
                type:
                - integer
                - 'null'
              name:
                description: Name of the tax or service charge.
                example: UT sales tax
                type: string
              percentageChargeRate:
                description: Tax or service charge percent. Null if FLAT_RATE
                example: '3'
                type:
                - string
                - 'null'
              serviceChargeClassification:
                description: Classification of tax or service charge.
                enum:
                - SERVICE_CHARGE
                - SALES_TAX
                - RETAIL_SALES_TAX
                type: string
              serviceChargeType:
                description: Type of tax or service charge.
                enum:
                - FLAT_RATE
                - PERCENTAGE_BASED
                type: string
            type: object
          type: array
        lineItems:
          items:
            description: Separate items or services that make up an invoice.
            properties:
              amount:
                description: Amount to be charged for the line item, represented in cents.
                example: 1099
                type: integer
              description:
                description: Description of the item or service being charged.
                example: Total
                type: string
            type: object
          type: array
        location:
          description: Location that the invoice belongs to.
          properties:
            organizationUid:
              description: Podium unique identifier for organization.
              example: 00000000-0000-0000-0000-000000000000
              format: uuid
              type:
              - string
              - 'null'
            uid:
              description: Podium unique identifier for location.
              example: 00000000-0000-0000-0000-000000000000
              format: uuid
              type:
              - string
              - 'null'
          type: object
        paidAt:
          description: When the invoice was paid.
          example: '2015-01-23T23:50:07Z'
          format: date-time
          type:
          - string
          - 'null'
        paymentNet:
          description: The amount of the money from the transaction delivered to the merchant less processing fees, represented in cents.
          example: 1000
          type:
          - integer
          - 'null'
        payments:
          items:
            description: Details of when a customer pays an invoice.
            properties:
              bankAccountLast4:
                description: Last four digits of the bank account used if bank transfers are used to make a payment.
                example: '1245'
                type:
                - string
                - 'null'
              bankAccountName:
                description: Name of the banking institute used if bank transfers are used to make a payment.
                example: The Bank
                type:
                - string
                - 'null'
              cardBrand:
                description: Card brand used if a card is used to make a payment.
                example: visa
                type:
                - string
                - 'null'
              cardFunding:
                description: Card type used if a card is used to make a payment.
                example: CREDIT
                type:
                - string
                - 'null'
              cardLast4:
                description: Last four digits of the card used if a card is used to make a payment.
                example: '4242'
                type:
                - string
                - 'null'
              createdAt:
                description: When the payment was made.
                example: '2015-01-23T23:50:07Z'
                format: date-time
                type:
                - string
                - 'null'
              declineCode:
                description: Code returned by the payment processor if a card was used and the payment was declined.
                example: card_not_supported
                type:
                - string
                - 'null'
              declineCodeMessage:
                description: A more descriptive message about the declideCode attribute.
                example: The card does not support this type of purchase.
                type:
                - string
                - 'null'
              fee:
                description: Transaction fee removed at the time of the transaction, represented in cents.
                example: 99
                type:
                - integer
                - 'null'
              feeBillingType:
                description: How the transaction fee is billed.
                example: per_deposit
                type:
                - string
                - 'null'
              feeCollectedAt:
                description: When the transaction fee was collected.
                example: '2015-01-23T23:50:07Z'
                format: date-time
                type:
                - string
                - 'null'
              interchangeFee:
                description: Transaction fee that is removed at the beginning of the following month if a merchant is on Interchange+, represented in cents.
                example: 50
                type:
                - integer
                - 'null'
              paidWithCardOnFile:
                description: Whether the payment was made with a card on file.
                example: true
                type:
                - boolean
                - 'null'
              refunds:
                items:
                  description: A refund can be for the full or partial amount of the payment. Thus there can be multiple refunds per transaction.
                  properties:
                    amount:
                      description: Amount refunded on an invoice, represented in cents.
                      example: 100
                      type:
                      - integer
                      - 'null'
              

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/podium/refs/heads/main/openapi/podium-invoice-api-openapi.yml