openapi: 3.0.0
info:
  title: Shippo external API.
  version: '2018-02-08'
  x-logo:
    url: https://docs.goshippo.com/images/shippo-logo.svg
  contact:
    name: Shippo Developer Platform
    url: https://goshippo.com/contact/
  description: Use this API to integrate with the Shippo service
servers:
  - url: https://api.goshippo.com
security:
  - APIKeyHeader: []
tags:
  - name: Invoices
    x-displayName: Invoices (beta)
    description: >-
      <b> Please note that the following endpoints are in beta and API contract
      is subject to change. </b>

      <br>

      <br>

      An invoice is a request for payment for Shippo services. It is a
      collection of invoice items. 

      You can query your invoice at any time to see your current charges. 

      Shippo sends invoices weekly or when your bill has exceeded $100.

      <a
      href="https://support.goshippo.com/hc/en-us/articles/360024703991-Shippo-Billing-FAQs"
      target="blank">Shippo Billing FAQs</a>.

      <SchemaDefinition
      schemaRef="#/components/schemas/Invoice"></SchemaDefinition>


      # Invoice Item

      Invoice items are the individual amounts owed to Shippo. They can
      represent a purchased label or a charge for a service. Invoice items also
      represent refunds. They are the line items in an invoice.

      <SchemaDefinition
      schemaRef="#/components/schemas/InvoiceItem"></SchemaDefinition>
paths:
  /invoices/{InvoiceObjectId}:
    get:
      description: >-
        <b> Endpoint is in beta and API contract is subject to change.</b>
        <br><br>Returns a single invoice using an object ID.
      operationId: GetInvoice
      parameters:
        - description: Object ID of the Invoice
          in: path
          name: InvoiceObjectId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '200':
          $ref: '#/components/responses/getInvoiceResponse'
      summary: Retrieve an invoice
      tags:
        - Invoices
      x-codeSamples:
        - label: cURL
          lang: cURL
          source: |-
            curl https://api.goshippo.com/invoices/{InvoiceObjectId}  \
            -H "Authorization: ShippoToken <API_TOKEN>" \
            -H "Content-Type: application/json"
  /invoices:
    get:
      description: >-
        <b> Endpoint is in beta and API contract is subject to change. </b>
        <br><br>

        Retrieves a collection of invoices that belong to the authenticated
        user. 

        Date range and invoice status filters can be used to filter the result
        set. The results are paginated. Please see

        <a href="https://docs.goshippo.com/docs/api_concepts/filtering/"
        target="blank"> filtering documentation</a> for more information

        on date filtering and pagination.
      operationId: ListInvoices
      summary: List all invoices
      parameters:
        - $ref: '#/components/parameters/PageNumberQueryParam'
        - $ref: '#/components/parameters/ResultsPerPageQueryParam'
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '200':
          $ref: '#/components/responses/listInvoicesResponse'
      tags:
        - Invoices
      x-codeSamples:
        - label: cURL
          lang: cURL
          source: |-
            curl https://api.goshippo.com/invoices?results=20&page=2  \
              -H "Authorization: ShippoToken <API_TOKEN>" \
              -H "Content-Type: application/json"
  /invoice-items:
    get:
      description: >-
        <b> Endpoint is in beta and API contract is subject to change. </b>
        <br><br>

        Retrieves a collection of invoice items that belong to the authenticated
        user. 

        Invoice object ID and object owner object ID can be used to filter the
        result set.

        The results are paginated. Please see <a
        href="https://docs.goshippo.com/docs/api_concepts/filtering/"
        target="blank"> filtering documentation</a> for more information

        on date filtering and pagination.
      operationId: ListInvoiceItemsTemplate
      summary: List all invoice items
      parameters:
        - description: >-
            The invoice object ID identifier of the Invoice whose Invoice Items
            you want to select.
          in: query
          name: invoiceObjectId
          required: false
          schema:
            type: string
        - description: >-
            The invoice number identifier of the Invoice whose Invoice Items you
            want to select.
          in: query
          name: invoiceNumber
          required: false
          schema:
            type: string
        - description: >-
            Account identifier for the owner of the Invoice Item. Use this to
            filter Invoice Items for 

            Shippo Managed Accounts.
          in: query
          name: shippoAccountId
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/PageNumberQueryParam'
        - $ref: '#/components/parameters/ResultsPerPageQueryParam'
        - $ref: '#/components/parameters/ShippoApiVersionHeader'
      responses:
        '200':
          $ref: '#/components/responses/listInvoiceItemsResponse'
      tags:
        - Invoices
      x-codeSamples:
        - label: cURL
          lang: cURL
          source: |-
            curl /invoice-items?results=20&page=2  \
              -H "Authorization: ShippoToken <API_TOKEN>" \
              -H "Content-Type: application/json"
components:
  parameters:
    PageNumberQueryParam:
      description: The page number you want to select
      in: query
      name: page
      schema:
        type: integer
        format: int64
        default: 1
    ResultsPerPageQueryParam:
      description: The number of results to return per page (max 100)
      in: query
      name: results
      schema:
        type: integer
        format: int64
        maximum: 100
        default: 25
    ShippoApiVersionHeader:
      description: String used to pick a non-default API version to use
      in: header
      name: SHIPPO-API-VERSION
      schema:
        type: string
  responses:
    getInvoiceResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Invoice'
    listInvoicesResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceListWrapper'
    listInvoiceItemsResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceItemListWrapper'
  schemas:
    ConversionAmount:
      description: Invoice Item's amount after currency conversion took place.
      properties:
        rate:
          example: '0.89'
          type: string
          description: >-
            Currency conversion rate, relative to USD, that was used to
            calculate the converted amount.
        time:
          type: string
          format: date-time
          description: Date and time the currency conversion took place.
        amount:
          description: The money amount after currency conversion.
          example: '4.91'
          type: string
        currency:
          description: >-
            The currency that 'amount' is in. The official ISO 4217 currency
            codes are used, e.g. "USD" or "EUR".

            <a href="http://www.xe.com/iso4217.php" target="blank">ISO 4217
            Standard</a>.
          example: USD
          type: string
      type: object
    AmountAndCurrencyCharged:
      description: >-
        The amount and currency that was charged after possible currency
        conversion occurred.
      properties:
        amount:
          description: The money amount
          example: '5.52'
          type: string
        currency:
          description: >-
            The currency that 'amount' is in. The official ISO 4217 currency
            codes are used, e.g. "USD" or "EUR".

            <a href="http://www.xe.com/iso4217.php" target="blank">ISO 4217
            Standard</a>.
          example: USD
          type: string
      type: object
    AmountAndCurrencyInvoiced:
      description: The amount and currency.
      properties:
        amount:
          description: The money amount
          example: '5.52'
          type: string
        currency:
          description: >-
            The currency that 'amount' is in. The official ISO 4217 currency
            codes are used, e.g. "USD" or "EUR".

            <a href="http://www.xe.com/iso4217.php" target="blank">ISO 4217
            Standard</a>.
          example: USD
          type: string
      type: object
    PaginatedList:
      properties:
        next:
          example: baseurl?page=3&results=10
          type: string
        previous:
          example: baseurl?page=1&results=10
          type: string
      type: object
    Invoice:
      properties:
        object_id:
          example: ec9f0d3adc9441449c85d315f0997fd5
          type: string
          description: Unique identifier of the given Invoice object
        object_created:
          format: date-time
          type: string
          description: Date and time of Invoice creation.
        object_updated:
          format: date-time
          type: string
          description: Date and time of last Invoice update.
        shippo_account:
          example: 915d94940ea54c3a80cbfa328722f5a1
          type: string
          description: Unique identifier of the user who the Invoice has been issued to.
        invoice_number:
          example: 234167
          type: string
          description: >-
            Human readable unique identifier of the given Invoice object that is
            displayed in the web app.
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        invoice_closed:
          format: date-time
          type: string
          description: >-
            Date and time of when the Invoice was posted and no new Invoice
            Items were added. Field will be null when invoice is still in the
            draft status.
        invoice_paid_date:
          format: date-time
          type: string
          description: >-
            Date and time of when the Invoice was successfully paid. Field will
            be null when invoice is not in the paid status.
        total_invoiced:
          $ref: '#/components/schemas/AmountAndCurrencyInvoiced'
        total_charged:
          $ref: '#/components/schemas/AmountAndCurrencyCharged'
      type: object
    InvoiceListWrapper:
      allOf:
        - $ref: '#/components/schemas/PaginatedList'
        - properties:
            results:
              items:
                $ref: '#/components/schemas/Invoice'
              type: array
    InvoiceStatus:
      enum:
        - DRAFT
        - POSTED
        - PAID
        - UNCOLLECTIBLE
        - VOID
      example: POSTED
      type: string
      description: The status of the Invoice.
    InvoiceItem:
      properties:
        object_id:
          example: ec9f0d3adc9441449c85d315f0997fd5
          type: string
          description: Unique identifier of the given Invoice Item object.
        object_created:
          format: date-time
          type: string
          description: Date and time of Invoice Item creation.
        object_updated:
          format: date-time
          type: string
          description: Date and time of last Invoice Item update.
        shippo_account:
          example: 915d94940ea54c3a80cbfa328722f5a1
          type: string
          description: >-
            Unique identifier of the user who the Invoice Item has been issued
            to.
        type:
          $ref: '#/components/schemas/InvoiceItemTypes'
          example: SUBSCRIPTION_PLAN_FEE
          type: string
        description:
          example: monthly subscription plan fee for 2019-08-24
          type: string
          description: Additional information about what the Invoice Item is for.
        amount:
          example: '5.54'
          type: string
          description: The money amount that the Invoice Item represents.
        currency:
          example: USD
          type: string
          description: >-
            The currency that 'amount' is in. The official ISO 4217 currency
            codes are used, e.g. "USD" or "EUR".

            <a href="http://www.xe.com/iso4217.php" target="blank">ISO 4217
            Standard</a>.
        charge_conversion:
          $ref: '#/components/schemas/ConversionAmount'
        invoice:
          example: 011044d8405e43bd8b1efe1c21f967df
          type: string
          description: Unique identifier of the Invoice that the Invoice Item belongs to.
        transaction:
          example: 915d94940ea54c3a80cbfa328722f5a1
          type: string
          description: >-
            Unique identifier of the Transaction that the Invoice Item
            represents. Not all Invoice Items are linked to a transaction.
      type: object
    InvoiceItemTypes:
      type: string
      enum:
        - LABEL_PAYMENT
        - LABEL_SURCHARGE
        - LABEL_REFUND
        - ONE_OFF_CREDIT
        - TRACK_FEE
        - ADDRESS_VALIDATION_FEE
        - SUBSCRIPTION_PLAN_FEE
        - PROMO_CODE_CREDIT
        - PREAUTH_CAPTURE
        - LABEL_PAYMENT_ADJUSTMENT
        - LABEL_REFUND_ADJUSTMENT
      description: >
        The type of the Invoice Item.

        |Type| Description|

        |:---|:---|

        | LABEL_PAYMENT | Invoice Item for the payment of a label. |

        | LABEL_SURCHARGE | Invoice Item for a surcharge of a label. See <a
        href="https://support.goshippo.com/hc/en-us/articles/115004734443-Understanding-Postal-Surcharges-in-Shippo">
        here </a> for more information. |

        | LABEL_REFUND | Invoice Item for a refund of a label. |

        | ONE_OFF_CREDIT | Invoice Item for credit given by Shippo. |

        | TRACK_FEE | Invoice Item for fees associated with tracking services. |

        | ADDRESS_VALIDATION_FEE | Invoice Item for fees associated with global
        address validation services. |

        | SUBSCRIPTION_PLAN_FEE | Invoice Item for subscription plan fees. |

        | PROMO_CODE_CREDIT | Invoice Item for promotional code related credits.
        |

        | PREAUTH_CAPTURE | Invoice Item for preauthorization capture.
        Represents a credit. See <a
        href="https://support.goshippo.com/hc/en-us/articles/4407966198171-Pre-Authorization-Charges-for-New-Accounts-in-Shippo">
        here </a> for more information. |

        | LABEL_PAYMENT_ADJUSTMENT | Invoice Item for adjustments on label
        purchases. |

        | LABEL_REFUND_ADJUSTMENT | Invoice Item for adjustments on label
        refunds. |
    InvoiceItemListWrapper:
      allOf:
        - $ref: '#/components/schemas/PaginatedList'
        - properties:
            results:
              items:
                $ref: '#/components/schemas/InvoiceItem'
              type: array
  securitySchemes:
    APIKeyHeader:
      in: header
      name: Authorization
      type: apiKey
