Invoice report - Shippo API Documentation

An invoice is a detailed breakdown of the cost associated with your label purchase. For details about invoices, see our billing guide. In addition to your invoice, you can also download an invoice report using the Shippo API. The Shippo API generates a new invoice report file daily. Use this guide to understand how to use the reports/invoices endpoint to retrieve your invoice report files.

Download invoice report

Find invoice report

The first step is to find the invoice report you want to download. Follow the example below to list all invoice reports. Use page and limit to navigate through your list of files.

List invoice files request

url -i -X GET \
'https://api.goshippo.com/v2/reports/invoices?page=MTA=' \
-H 'Authorization: ShippoToken <API_TOKEN>'

List invoice file response

{
    {
    "page_info": {
        "next": "MjA=",
        "prev": "MA=="
    },
    "resources": [
        {
            "date": "2024-05-01T04:06:11.000000Z",
            "file_id": "636a9611-62fb-4eea-bde2-0fdd3b21e2d2"
        },
        {
            "date": "2024-05-02T04:11:09.000000Z",
            "file_id": "508b45e0-1221-42ca-8042-7a459c09ac13"
        }
    ]
    }
}

Retrieve invoice report

The second step is to retrieve the file. Use the file_id from the first step, to download the invoice report. A successful response returns a 302 status code. Your client should automatically follow the redirected link to download the file. Follow the example below to download your invoice report.

Get invoice file request

curl -i -X GET \
'https://api.goshippo.com/v2/reports/invoices/508b45e0-1221-42ca-8042-7a459c09ac13' \
-H 'Authorization: ShippoToken <API_TOKEN>'

Get invoice file response

//redirect to CSV file

NoteThe redirect is valid for only five minutes. If you wish to download the file again, you must create a new request.

Invoice report file

The invoice report is shared in CSV file format. The following table shows a description of each column in the report file.

Column title	Description	Example
User UUID	Invoice owner (User UUID and Merchant UUID are different for platform accounts, but same for public api accounts)	9ff12ea3-a5e4-4ed7-a9d0-b1f967a25c2a
Merchant ID	External Identifier for user/merchant who made the transaction/label (applicable for platform users)	acc88d88-48a4-4b13-9ebe-f61ce3bea8f7
Invoice Object ID	UUID of the invoice	c9a2b3a4-d5f6-4b7d-a1e0-c6d7e3f4g5h6
Invoice Creation Date (UTC)	Invoice creation timestamp	2024-06-11T16:02:55.452Z
Invoice Close Date (UTC)	Invoice closing timestamp	2024-06-12T17:02:12.126Z
Invoice Status	Status of invoice payment	PAID
Invoice Paid Date (UTC)	Invoice amount paid timestamp	2024-06-12T01:02:12.053Z
Invoice Item Object ID	UUID identifier for each invoice item	f4c3b2a1-d5e6-4a7d-b0e1-c2d3f4e5g6h7
Invoice Item Amount	Invoice item amount in specified currency - postage price + insurance price + label fee - subscription fee is not accounted for here. If someone has a subscription plan, label fee is 0	6
Invoice Item Currency	Currency format for the invoice item amount values	USD
Invoice Item Type	Invoice Item type	LABEL_PAYMENT
Description	Description of the invoice item. Identifies details for surcharges & address corrections (text provided by carrier)	Surcharge: Declared weight was 0.25 lb, sampled weight was 0.3125 lb
Transaction UUID	External Identifier for each transaction/label	b6fce8a8b1fe41adbe2b80594d62fad9
Transaction Entry Point	Source of entry	Shippo
Transaction Date (UTC)	Timestamp of transaction creation	2024-06-11T22:28:00.740Z
Tracking Number	Carrier specific tracking number for the label generated	1ZG75K320332928213’
Transaction Metadata
Rate Amount		5
Rate Currency		CAD
Rate Exchange Rate from USD	Exchange rate from USD to currency in sender country (exchange rate is updated hourly)	1.38
Insurance Fee	Insurance amount for the invoice item in specified currency	1
Carrier	Carrier Name	UPS
Rate Service Level Name	Shipping service level	Ground
Carrier Zone	Zone defined by carrier.	5
Sender City	Sender info	San Francisco
Sender State	Sender info	CA
Sender Zip	Sender info	94103
Sender Country	Sender info	UNITED STATES
Recipient City	Recipient info	San Francisco
Recipient State	Recipient info	CA
Recipient Zip	Recipient info	94103
Recipient Country	Recipient info	UNITED STATES
Shipment Metadata
Shipment Reference 1
Shipment Reference 2
Shipment Extra		"""bypass_address_validation"": false, ""reference_1"": ""jennicam"""
Shipment Insured Amount	Amount the insurance covers up to.	4.2
Shipment Insured Amount Currency	Currency the insurance amount is originally in. Should be paired with Insurance Fee.	USD
Shipment Signature Confirmation Cost	Cost of signature confirmation	2
Parcel Length	Parcel Length	12
Parcel Width	Parcel Width	12
Parcel Height	Parcel Height	12
Parcel Dimensions Unit	Parcel Dimensions Unit	in
Parcel Weight	Parcel Weight	640
Parcel Weight Unit	Parcel Weight Unit	oz

​Download invoice report

​Find invoice report

​Retrieve invoice report

​Invoice report file

Download invoice report

Find invoice report

Retrieve invoice report

Invoice report file