Preview the upcoming usage invoice
curl --request GET \
--url https://api.example.com/v1/invoices/upcoming \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/v1/invoices/upcoming"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/v1/invoices/upcoming', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/invoices/upcoming",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/invoices/upcoming"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/invoices/upcoming")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/invoices/upcoming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "invc_1Q2w3E4r",
"object": "invoice",
"livemode": true,
"created": 123,
"kind": "transport",
"status": "draft",
"currency": "<string>",
"lines": [
{
"kind": "transport",
"amount": {
"amount": 123,
"currency": "usd"
},
"id": "<string>",
"shipment": "<string>",
"tracking_number": "<string>",
"service": "<string>",
"description": "<string>",
"charge_kind": "<string>",
"reason": "dimensional_reweigh",
"billed_weight": {
"value": 123,
"unit": "g"
},
"zone": "<string>",
"declared": {},
"audited": {},
"meter": "<string>",
"quantity": 123,
"unit_amount": 123,
"tax": {
"amount": 123,
"currency": "usd"
},
"external_ref": "<string>"
}
],
"totals": {
"subtotal": {
"amount": 123,
"currency": "usd"
},
"tax": {
"amount": 123,
"currency": "usd"
},
"total": {
"amount": 123,
"currency": "usd"
},
"paid": {
"amount": 123,
"currency": "usd"
},
"due": {
"amount": 123,
"currency": "usd"
}
},
"updated": 123,
"direction": "payable",
"issuer": {
"account": "<string>",
"integration": "<string>",
"connection": "<string>",
"name": "<string>",
"tax_ids": [
{
"type": "eori",
"value": "<string>",
"country": "<string>"
}
]
},
"recipient": {
"account": "<string>",
"integration": "<string>",
"connection": "<string>",
"name": "<string>",
"tax_ids": [
{
"type": "eori",
"value": "<string>",
"country": "<string>"
}
]
},
"number": "<string>",
"issued_on": "2023-12-25",
"due_on": "2023-12-25",
"period": {
"from": "2023-12-25",
"to": "2023-12-25"
},
"reconciliation": {
"id": "<string>",
"status": "<string>",
"matched": 123,
"mismatched": 123,
"unknown": 123,
"disputed_amount": {
"amount": 123,
"currency": "usd"
}
},
"source": {
"type": "issued",
"format": "<string>",
"file": "<string>",
"job": "<string>"
},
"documents": [
{
"id": "<string>",
"object": "document",
"type": "label",
"format": "pdf",
"size": "<string>",
"url": "<string>",
"url_expires_at": 123,
"data": "<string>",
"handling_unit": "<string>",
"bundle": [
"<string>"
],
"template": "<string>",
"template_version": 123,
"related": {
"type": "<string>",
"id": "<string>"
},
"file": "<string>",
"sha256": "<string>"
}
],
"payments": [
"<string>"
],
"external_ids": [
{
"source": "<string>",
"id": "<string>"
}
],
"user_metadata": {},
"carrier_metadata": {},
"system_metadata": {
"source": "api",
"created_by": {
"type": "api_key",
"id": "<string>"
},
"request_id": "<string>",
"idempotency_key": "<string>",
"batch": "<string>",
"generated": true,
"test_scenario": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}Billing
Preview the upcoming usage invoice
GET
/
v1
/
invoices
/
upcoming
Preview the upcoming usage invoice
curl --request GET \
--url https://api.example.com/v1/invoices/upcoming \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/v1/invoices/upcoming"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/v1/invoices/upcoming', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v1/invoices/upcoming",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v1/invoices/upcoming"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v1/invoices/upcoming")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/invoices/upcoming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "invc_1Q2w3E4r",
"object": "invoice",
"livemode": true,
"created": 123,
"kind": "transport",
"status": "draft",
"currency": "<string>",
"lines": [
{
"kind": "transport",
"amount": {
"amount": 123,
"currency": "usd"
},
"id": "<string>",
"shipment": "<string>",
"tracking_number": "<string>",
"service": "<string>",
"description": "<string>",
"charge_kind": "<string>",
"reason": "dimensional_reweigh",
"billed_weight": {
"value": 123,
"unit": "g"
},
"zone": "<string>",
"declared": {},
"audited": {},
"meter": "<string>",
"quantity": 123,
"unit_amount": 123,
"tax": {
"amount": 123,
"currency": "usd"
},
"external_ref": "<string>"
}
],
"totals": {
"subtotal": {
"amount": 123,
"currency": "usd"
},
"tax": {
"amount": 123,
"currency": "usd"
},
"total": {
"amount": 123,
"currency": "usd"
},
"paid": {
"amount": 123,
"currency": "usd"
},
"due": {
"amount": 123,
"currency": "usd"
}
},
"updated": 123,
"direction": "payable",
"issuer": {
"account": "<string>",
"integration": "<string>",
"connection": "<string>",
"name": "<string>",
"tax_ids": [
{
"type": "eori",
"value": "<string>",
"country": "<string>"
}
]
},
"recipient": {
"account": "<string>",
"integration": "<string>",
"connection": "<string>",
"name": "<string>",
"tax_ids": [
{
"type": "eori",
"value": "<string>",
"country": "<string>"
}
]
},
"number": "<string>",
"issued_on": "2023-12-25",
"due_on": "2023-12-25",
"period": {
"from": "2023-12-25",
"to": "2023-12-25"
},
"reconciliation": {
"id": "<string>",
"status": "<string>",
"matched": 123,
"mismatched": 123,
"unknown": 123,
"disputed_amount": {
"amount": 123,
"currency": "usd"
}
},
"source": {
"type": "issued",
"format": "<string>",
"file": "<string>",
"job": "<string>"
},
"documents": [
{
"id": "<string>",
"object": "document",
"type": "label",
"format": "pdf",
"size": "<string>",
"url": "<string>",
"url_expires_at": 123,
"data": "<string>",
"handling_unit": "<string>",
"bundle": [
"<string>"
],
"template": "<string>",
"template_version": 123,
"related": {
"type": "<string>",
"id": "<string>"
},
"file": "<string>",
"sha256": "<string>"
}
],
"payments": [
"<string>"
],
"external_ids": [
{
"source": "<string>",
"id": "<string>"
}
],
"user_metadata": {},
"carrier_metadata": {},
"system_metadata": {
"source": "api",
"created_by": {
"type": "api_key",
"id": "<string>"
},
"request_id": "<string>",
"idempotency_key": "<string>",
"batch": "<string>",
"generated": true,
"test_scenario": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"carrier": {
"id": "<string>",
"connection": "<string>",
"code": "<string>",
"message": "<string>"
},
"shipment": "<string>",
"details": [
{
"code": "<string>",
"message": "<string>",
"param": "<string>"
}
]
}
}Authorizations
apiKeyoauth2
sk_test_ / sk_live_ / rk_test_ / rk_live_ keys
Headers
Act on behalf of a connected account (acct_...)
Response
OK
Prefixed invc_
Example:
"invc_1Q2w3E4r"
Available options:
invoice Unix timestamp (seconds)
Available options:
transport, usage, settlement, duties, subscription, credit_note Available options:
draft, open, partially_paid, paid, overdue, disputed, void, uncollectible Show child attributes
Show child attributes
Show child attributes
Show child attributes
Unix timestamp (seconds)
Available options:
payable, receivable Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Client-writable. Up to 50 string key/value pairs. Never sent to carriers.
Show child attributes
Show child attributes
Read-only. Carrier-returned data not modelled by the spec (routing codes, internal IDs). Untrusted and unversioned; keys may change with the carrier's API.
Read-only. Implementer provenance. Implementer-specific keys are prefixed x_.
Show child attributes
Show child attributes