Skip to content
/
List all invoices

Shippo external API. (2018-02-08)

Use this API to integrate with the Shippo service

Download OpenAPI description
Invoices.json
Invoices.yaml
Overview
URL
https://goshippo.com/contact/
Languages
Servers
https://api.goshippo.com

Invoices (beta)

Please note that the following endpoints are in beta and API contract is subject to change.

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. Shippo Billing FAQs.

Operations

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.

Retrieve an invoice

Request

Endpoint is in beta and API contract is subject to change.

Returns a single invoice using an object ID.

Security
APIKeyHeader
Path
InvoiceObjectIdstringrequired

Object ID of the Invoice

Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

curl https://api.goshippo.com/invoices/{InvoiceObjectId}  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"

Responses

Bodyapplication/json
object_idstring

Unique identifier of the given Invoice object

Example: "ec9f0d3adc9441449c85d315f0997fd5"
object_createdstring(date-time)

Date and time of Invoice creation.

object_updatedstring(date-time)

Date and time of last Invoice update.

shippo_accountstring

Unique identifier of the user who the Invoice has been issued to.

Example: "915d94940ea54c3a80cbfa328722f5a1"
invoice_numberstring

Human readable unique identifier of the given Invoice object that is displayed in the web app.

Example: 234167
statusstring(InvoiceStatus)

The status of the Invoice.

Enum"DRAFT""POSTED""PAID""UNCOLLECTIBLE""VOID"
Example: "POSTED"
invoice_closedstring(date-time)

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_datestring(date-time)

Date and time of when the Invoice was successfully paid. Field will be null when invoice is not in the paid status.

total_invoicedobject(AmountAndCurrencyInvoiced)

The amount and currency.

total_chargedobject(AmountAndCurrencyCharged)

The amount and currency that was charged after possible currency conversion occurred.

Response
application/json
{
  "object_id": "ec9f0d3adc9441449c85d315f0997fd5",
  "object_created": "2019-08-24T14:15:22Z",
  "object_updated": "2019-08-24T14:15:22Z",
  "shippo_account": "915d94940ea54c3a80cbfa328722f5a1",
  "invoice_number": 234167,
  "status": "POSTED",
  "invoice_closed": "2019-08-24T14:15:22Z",
  "invoice_paid_date": "2019-08-24T14:15:22Z",
  "total_invoiced": {
    "amount": "5.52",
    "currency": "USD"
  },
  "total_charged": {
    "amount": "5.52",
    "currency": "USD"
  }
}

List all invoices

Request

Endpoint is in beta and API contract is subject to change.

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 filtering documentation for more information on date filtering and pagination.

Security
APIKeyHeader
Query
pageinteger(int64)

The page number you want to select

Default 1
resultsinteger(int64)<= 100

The number of results to return per page (max 100)

Default 25
Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

curl https://api.goshippo.com/invoices?results=20&page=2  \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json"

Responses

Bodyapplication/json
nextstring
Example: "baseurl?page=3&results=10"
previousstring
Example: "baseurl?page=1&results=10"
resultsArray of objects(Invoice)
Response
application/json
{
  "next": "baseurl?page=3&results=10",
  "previous": "baseurl?page=1&results=10",
  "results": [
    { … }
  ]
}

List all invoice items

Request

Endpoint is in beta and API contract is subject to change.

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 filtering documentation for more information on date filtering and pagination.

Security
APIKeyHeader
Query
invoiceObjectIdstring

The invoice object ID identifier of the Invoice whose Invoice Items you want to select.

invoiceNumberstring

The invoice number identifier of the Invoice whose Invoice Items you want to select.

shippoAccountIdstring

Account identifier for the owner of the Invoice Item. Use this to filter Invoice Items for Shippo Managed Accounts.

pageinteger(int64)

The page number you want to select

Default 1
resultsinteger(int64)<= 100

The number of results to return per page (max 100)

Default 25
Headers
SHIPPO-API-VERSIONstring

String used to pick a non-default API version to use

curl /invoice-items?results=20&page=2  \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json"

Responses

Bodyapplication/json
nextstring
Example: "baseurl?page=3&results=10"
previousstring
Example: "baseurl?page=1&results=10"
resultsArray of objects(InvoiceItem)
Response
application/json
{
  "next": "baseurl?page=3&results=10",
  "previous": "baseurl?page=1&results=10",
  "results": [
    { … }
  ]
}