API Documentation | Bitcoin Postage

Prerequisites for using our API

We provide a REST API to help you create postage labels with your application.

Before you can start using the API, you need to do the following:

Create an account
Create an API access

Authentication

Once you've registered and created your API access, you will have access to your API key and secret. These are required when making calls to the API. You can have multiple API access codes, which will allow you to manage multiple applications under the same account.

Making Requests

All requests to our API are made with POST verbs. When making requests, arguments are passed via params. If you're using one of our plugins, the requests are handled for you automatically when you call the appropriate function.

Endpoints

Get Rates

Displays the available postage services and rates for a given package

Required fields

key : API key
secret : API secret
to_name : Name of recipient
to_street : Street address of recipient
to_street2 : Address Line 2 of recipient
to_city : City of recipient
to_state : State of recipient
to_zip : ZIP code of recipient
to_country : Country of recipient
to_phone : Phone number of recipient
from_name : Name of sender
from_street : Street address of sender
from_street2 : Address Line 2 of sender
from_city : City of sender
from_state : State of sender
from_zip : ZIP code of sender
from_country : Country of sender
from_phone : Phone number of sender
package_type : List of available package types can be found here
carrier : List of available carriers can be found here. If you want to get rates for all carriers, use the value - all.
serviceoption : Only if using FedEx or UPS - List of available service options can be found here
weight_oz : Ounces remainder of package weight (not full weight in ounces)
weight_lbs : Pounds of package weight (integer - submit remainder as ounces in above parameter)
height : Inches of package height
width : Inches of package width
depth : Inches of package depth/length

HTTP request

POST https://bitcoinpostage.info/api/get-rates

Example request

											
												curl -d "key=[API key]&secret=[API secret]&to_name=[to_name]&to_street=[to_street]&to_city=[to_city]&to_state=[to_state]&to_zip=[to_zip]&to_country=[to_country]&to_phone=[to_phone]&from_name=[from_name]&from_street=[from_street]&from_street2=[from_street2]&from_city=[from_city]&from_state=[from_state]&from_zip=[from_zip]&from_country=[from_country]&from_phone=[from_phone]&package_type=[package_type]&carrier=[carrier]&weight_oz=[weight_oz]&weight_lbs=[weight_lbs]&height=[height]&width=[width]&depth=[depth]" https://bitcoinpostage.info/api/get_rates

Example output

										
											[

												{

												"service":"Express",

												"service_display":"Express",

												"rate":"28.88",

												"carrier":"USPS",

												"est_delivery_days":"1-2",

												"currency":"USD"

												},

											{

											"service":"GroundAdvantage",

											"service_display":"GroundAdvantage",

											"rate":"3.12",

											"carrier":"USPS",

											"est_delivery_days":3,

											"currency":"USD"

											},

											{

											"service":"MediaMail",

											"service_display":"Media Mail",

											"rate":"3.11",

											"carrier":"USPS",

											"est_delivery_days":6,

											"currency":"USD"

											},

											{

											"service":"ParcelSelect",

											"service_display":"Parcel Select",

											"rate":"8.48",

											"carrier":"USPS",

											"est_delivery_days":6,

											"currency":"USD"

											},

											{

											"service":"Priority",

											"service_display":"Priority",

											"rate":"8.64",

											"carrier":"USPS",

											"est_delivery_days":2,

											"currency":"USD"

											}

											]

Create Purchase

Purchases a shipping label. Please note that this function uses your account's credit balance.

Required fields

key : API key
secret : API secret
to_name : Name of recipient
to_street : Street address of recipient
to_street2 : Address Line 2 of recipient
to_city : City of recipient
to_state : State of recipient
to_zip : ZIP code of recipient
to_country : Country of recipient
to_phone : Phone number of recipient
from_name : Name of sender
from_street : Street address of sender
from_street2 : Address Line 2 of sender
from_city : City of sender
from_state : State of sender
from_zip : ZIP code of sender
from_country : Country of sender
from_phone : Phone number of sender
package_type : List of available package types can be found here
carrier : List of available carriers can be found here
service : Service chosen from the Get Rates endpoint output
serviceoption : Only if using FedEx or UPS - List of available service options can be found here
weight_oz : Ounces remainder of package weight (not full weight in ounces)
weight_lbs : Pounds of package weight (integer - submit remainder as ounces in above parameter)
height : Inches of package height
width : Inches of package width
depth : Inches of package depth/length
label_format : Label format PNG or PDF
test_mode : The value true enables the test mode. Allows you to test the work of the api, without withdrawing credits. Works only for USPS.
delivery_confirmation : If you want to request a signature, you can pass ADULT_SIGNATURE or SIGNATURE. You may also request NO_SIGNATURE to leave the package at the door.

HTTP request

POST https://bitcoinpostage.info/api/create-purchase

Example request

											
												curl -d "key=[API key]&secret=[API secret]&to_name=[to_name]&to_street=[to_street]&to_street2=[to_street2]&to_city=[to_city]&to_state=[to_state]&to_zip=[to_zip]&to_country=[to_country]&to_phone=[to_phone]&from_name=[from_name]&from_street=[from_street]&from_street2=[from_street2]&from_city=[from_city]&from_state=[from_state]&from_zip=[from_zip]&from_country=[from_country]&from_phone=[from_phone]&package_type=[package_type]&carrier=[carrier]&service=[service]&weight_oz=[weight_oz]&weight_lbs=[weight_lbs]&height=[height]&width=[width]&depth=[depth]&delivery_confirmation=[delivery_confirmation]" https://bitcoinpostage.info/api/create-purchase

Example output

										
											{

											"order_timestamp":"1563268442",

											"items":[{

											"shipment_id":"shp_...",

											"carrier":"usps",

											"service":"GroundAdvantage",

											"from_name":"[name]",

											"to_name":"[name]",

											"price":"3.12",

											"currency":"USD",

											"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",

											"tracking_no":"944..."

											}],

											"order_id":"a5e...",

											"remaining_credits":53.07

											}

Create International Purchase

Purchases a shipping label. Please note that this function uses your account's credit balance.

Required fields

key : API key
secret : API secret
to_name : Name of recipient
to_street : Street address of recipient
to_street2 : Address Line 2 of recipient
to_city : City of recipient
to_state : State of recipient
to_zip : ZIP code of recipient
to_country : Country of recipient
to_phone : Phone number of recipient
from_name : Name of sender
from_street : Street address of sender
from_street2 : Address Line 2 of sender
from_city : City of sender
from_state : State of sender
from_zip : ZIP code of sender
from_country : Country of sender
from_phone : Phone number of sender
package_type : List of available package types can be found here
carrier : List of available carriers can be found here
service : Service chosen from the Get Rates endpoint output
serviceoption : Only if using FedEx or UPS - List of available service options can be found here
weight_oz : Ounces remainder of package weight (not full weight in ounces)
weight_lbs : Pounds of package weight (integer - submit remainder as ounces in above parameter)
height : Inches of package height
width : Inches of package width
depth : Inches of package depth/length
test_mode : The value true enables the test mode. Allows you to test the work of the api, without withdrawing credits. Works only for USPS.
delivery_confirmation : If you want to request a signature, you can pass ADULT_SIGNATURE or SIGNATURE. You may also request NO_SIGNATURE to leave the package at the door.
type_contents : Type of Contents: Documents, Gift, Merchandise, Returned Goods, Sample
signer : Signer / Name
customs : Contains information relating to each product within the package. There can be several in one request.
Fields separated by :: Quantity, Description, Total Value($), Total Weight(oz), Country code of origin, Tariff Number
Example - 2::Books::100::20::US::49019900

HTTP request

POST https://bitcoinpostage.info/api/create-purchase

Example request

											
												curl -d "key=[API key]&secret=[API secret]&to_name=[to_name]&to_street=[to_street]&to_street2=[to_street2]&to_city=[to_city]&to_state=[to_state]&to_zip=[to_zip]&to_country=[to_country]&to_phone=[to_phone]&from_name=[from_name]&from_street=[from_street]&from_street2=[from_street2]&from_city=[from_city]&from_state=[from_state]&from_zip=[from_zip]&from_country=[from_country]&from_phone=[from_phone]&package_type=[package_type]&carrier=[carrier]&service=[service]&weight_oz=[weight_oz]&weight_lbs=[weight_lbs]&height=[height]&width=[width]&depth=[depth]&delivery_confirmation=[delivery_confirmation]&type_contents=[type_contents]&signer=[signer]&customs[]=[customs]&customs[]=[customs]" https://bitcoinpostage.info/api/create-purchase

Example output

										
											{

											"order_timestamp":"1563268443",

											"items":[{

											"shipment_id":"shp_...",

											"carrier":"usps",

											"service":"GroundAdvantage",

											"from_name":"[name]",

											"to_name":"[name]",

											"price":"3.12",

											"currency":"USD",

											"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",

											"tracking_no":"944..."

											}],

											"order_id":"a5e...",

											"remaining_credits":53.07

											}

Create Batch Purchase

Purchases up to 5 shipping labels at once. Please note that this function uses your account's credit balance.

Required fields

key : API key
secret : API secret
shipments : An array of shipment objects

Shipment object fields

to_name : Name of recipient
to_street : Street address of recipient
to_street2 : Address Line 2 of recipient
to_city : City of recipient
to_state : State of recipient
to_zip : ZIP code of recipient
to_country : Country of recipient
to_phone : Phone number of recipient
from_name : Name of sender
from_street : Street address of sender
from_street2 : Address Line 2 of sender
from_city : City of sender
from_state : State of sender
from_zip : ZIP code of sender
from_country : Country of sender
from_phone : Phone number of sender
package_type : List of available package types can be found here
carrier : List of available carriers can be found here
service : Service chosen from the Get Rates endpoint output
serviceoption : Only if using FedEx or UPS - List of available service options can be found here
weight_oz : Ounces remainder of package weight (not full weight in ounces)
weight_lbs : Pounds of package weight (integer - submit remainder as ounces in above parameter)
height : Inches of package height
width : Inches of package width
depth : Inches of package depth/length
label_format : Label format PNG or PDF
delivery_confirmation : If you want to request a signature, you can pass ADULT_SIGNATURE or SIGNATURE. You may also request NO_SIGNATURE to leave the package at the door.
test_mode : The value true enables the test mode. Allows you to test the work of the api, without withdrawing credits. Works only for USPS.

Attention

This request needs to be sent in JSON format, unlike other API requests.

HTTP request

POST https://bitcoinpostage.info/api/create-batch-purchase

Example request

											
												curl -X POST -H "Content-Type: application/json" -d '{

												"key": "[API key]",

												"secret": "[API secret]",

												"shipments": [

												{"to_name": "[to_name]",

												"to_street": "[to_street]",

												"to_street2": "[to_street2]",

												"to_city": "[to_city]",

												"to_state": "[to_state]",

												"to_zip": "[to_zip]",

												"to_country": "[to_country]",

												"to_phone": "[to_phone]",

												"from_name": "[from_name]",

												"from_street": "[from_street]",

												"from_street2": "[from_street2]",

												"from_city": "[from_city]",

												"from_state": "[from_state]",

												"from_zip": "[from_zip]",

												"from_country": "[from_country]",

												"from_phone": "[from_phone]",

												"package_type": "[package_type]",

												"carrier": "[carrier]",

												"service": "[service]",

												"weight_oz": "[weight_oz]",

												"weight_lbs": "[weight_lbs]",

												"height": "[height]",

												"width": "[width]",

												"depth": "[depth]"},

												"delivery_confirmation": "[delivery_confirmation]",

												...

												{"to_name": "[to_name]",

												"to_street": "[to_street]",

												"to_street2": "[to_street2]",

												"to_city": "[to_city]",

												"to_state": "[to_state]",

												"to_zip": "[to_zip]",

												"to_country": "[to_country]",

												"to_phone": "[to_phone]",

												"from_name": "[from_name]",

												"from_street": "[from_street]",

												"from_street2": "[from_street2]",

												"from_city": "[from_city]",

												"from_state": "[from_state]",

												"from_zip": "[from_zip]",

												"from_country": "[from_country]",

												"from_phone": "[from_phone]",

												"package_type": "[package_type]",

												"carrier": "[carrier]",

												"service": "[service]",

												"weight_oz": "[weight_oz]",

												"weight_lbs": "[weight_lbs]",

												"height": "[height]",

												"width": "[width]",

												"depth": "[depth]"}

												"delivery_confirmation": "[delivery_confirmation]",

												]

												}' https://bitcoinpostage.info/api/create-batch-purchase

Example output

										
											{

											"order_timestamp":"1563268442",

											"items":[{

											"shipment_id":"shp_...",

											"carrier":"usps",

											"service":"GroundAdvantage",

											"from_name":"[name]",

											"to_name":"[name]",

											"price":"3.12",

											"currency":"USD",

											"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",

											"tracking_no":"944..."

											}],

											"order_id":"a5e..."
,
											"remaining_credits":50..

											},

											...

											{

											"order_timestamp":"1563268442",

											"items":[{

											"shipment_id":"shp_...",

											"carrier":"usps",

											"service":"GroundAdvantage",

											"from_name":"[name]",

											"to_name":"[name]",

											"price":"3.12",

											"currency":"USD",

											"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",

											"tracking_no":"944..."

											}],

											"order_id":"a5e..."
,
											"remaining_credits":40..

											}

Retrieve Purchase

Retrieves a previously created shipping label.

Required fields

key : API key
secret : API secret
order_id : Order ID returned by the Create Purchase endpoint

HTTP request

POST https://bitcoinpostage.info/api/retrieve-purchase

Example request

											
												curl -d "key=[API key]&secret=[API secret]&order_id=[order_id]" https://bitcoinpostage.info/api/retrieve-purchase

Example output

										
											{

											"order_timestamp":"1563268443",

											"items":[{

											"shipment_id":"shp_...",

											"carrier":"usps",

											"service":"GroundAdvantage",

											"from_name":"[name]",

											"to_name":"[name]",

											"price":"3.12",

											"currency":"USD",

											"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",

											"tracking_no":"944..."

											}],

											"order_id":"a5e...",

											"remaining_credits":53.07

											}

Charge Credits

Creates a pending transaction to charge your account. Once you complete the bitcoin transaction to the address specified, your account will automatically be charged. Please note that sending the wrong amount will result in failing to charge your account, and any given address is only usable for a single transaction.

Required fields

key : API key
secret : API secret
amount : Amount in USD you wish to charge
currency : BTC, XMR or LTC

HTTP request

POST https://bitcoinpostage.info/api/charge-credits

Example request

											
												curl -d "key=[API key]&secret=[API secret]&amount=[amount]&currency=[currency]" https://bitcoinpostage.info/api/charge-credits

Example output

										
										{

										"address":"35G7xaUG91odHPmhsSPGPsQyzVzXeH4sFK",

										"id":"6512bd43d9caa6e02c990b0a82652dca",

										"amount":"0.00280100",

										"timestamp":"1563269563",

										"credits":"30",

										"purchase_id":"89186"

										"currency":"btc",

										}

Get Credits

Retrieves your current credit balance.

Required fields

key : API key
secret : API secret

HTTP request

POST https://bitcoinpostage.info/api/get-credits

Example request

											
												curl -d "key=[API key]&secret=[API secret]" https://bitcoinpostage.info/api/get-credits

Example output

										
											{

											"credits":"977"

											}

Orders List

Retrieves your orders list.

Required fields

key : API key
secret : API secret

HTTP request

POST https://bitcoinpostage.info/api/orders

Example request

											
												curl -d "key=[API key]&secret=[API secret]" https://bitcoinpostage.info/api/orders

Example output

										
											[{
"order_id":"10001",
"order_timestamp":"1615233760",
"price":"9.84"
},
{
"order_id":"10005",
"order_timestamp":"1610977567",
"price":"22.36"
}]

Retrieve Purchase

Retrieves all shipments from your order.

Required fields

key : API key
secret : API secret
order_id : Order ID

HTTP request

POST https://bitcoinpostage.info/api/retrieve-order

Example request

											
												curl -d "key=[API key]&secret=[API secret]&order_id=[Order ID]" https://bitcoinpostage.info/api/retrieve-order

Example output

										
										[{
"from":"[name]",
"to":"[name]",
"tracking_no":"944...",
"shipment_id":"shp_...",
"carrier":"usps"
},
{
"from":"[name]",
"to":"[name]",
"tracking_no":"945...",
"shipment_id":"shp_...",
"carrier":"usps"
}]

Register Tracking Number

When the tracking number is successfully registered and the package status changes, a notification will be sent to the webhook URL

Each tracking number costs 0.04 taking from your credits.

Required fields

key : API key
secret : API secret
number : Tracking number
webhook_url : Webhook URL

Optional fields

tag : A tag you can note anything down with no more than 100 characters.

HTTP request

POST https://bitcoinpostage.info/api/register-track

Example request

											
												curl -d "key=[API key]&secret=[API secret]&number=[Tracking number]&number=[Webhook URL]" https://bitcoinpostage.info/api/register-track

Example output

										
										{
"event":"TRACKING_UPDATED",
"data":{
"number":"1Z2617V10397725789",
 "carrier":3011,
"tag":null
}
}

Stop Tracking

Use this to stop the tracking of a tracking number.

Required fields

key : API key
secret : API secret
number : Tracking number

HTTP request

POST https://bitcoinpostage.info/api/stop-track

Example request

											
												curl -d "key=[API key]&secret=[API secret]&number=[Tracking number]" https://bitcoinpostage.info/api/stop-track

Example output

										
										 {

                  "code": 0,

                  "data": {

                  "accepted": [

                  {

                  "number": "1Z2617V10397725789",

                  "carrier": "3011"

                  }

                  ]

                  }

                  }

Register Tracking Number

Restart the automatic tracking for a tracking number that has beem stopped.

Required fields

key : API key
secret : API secret
number : Tracking number

HTTP request

POST https://bitcoinpostage.info/api/retrack-shipment

Example request

											
												curl -d "key=[API key]&secret=[API secret]&number=[Tracking number]" https://bitcoinpostage.info/api/retrack-shipment

Example output

										
										 {

                  "code": 0,

                  "data": {

                  "accepted": [

                  {

                  "number": "1Z2617V10397725789",

                  "carrier": "3011"

                  }

                  ]

                  }

                  }

Bitcoin Postage API Documentation

Prerequisites for using our API

Authentication

Making Requests

Endpoints

Get Rates

Required fields

HTTP request

Example request

Example output

Create Purchase

Required fields

HTTP request

Example request

Example output

Create International Purchase

Required fields

HTTP request

Example request

Example output

Create Batch Purchase

Required fields

Shipment object fields

Attention

HTTP request

Example request

Example output

Retrieve Purchase

Required fields

HTTP request

Example request

Example output

Charge Credits

Required fields

HTTP request

Example request

Example output

Get Credits

Required fields

HTTP request

Example request

Example output

Orders List

Required fields

HTTP request

Example request

Example output

Retrieve Purchase

Required fields

HTTP request

Example request

Example output

Register Tracking Number

Required fields

Optional fields

HTTP request

Example request

Example output

Stop Tracking

Required fields

HTTP request

Example request

Example output

Register Tracking Number

Required fields

HTTP request

Example request

Example output