Introduction

We provide a REST API to help you create postage labels with your application. To get started, you will need to register and create 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_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_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
  • 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 http://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_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] http://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":"First",
"service_display":"First",
"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_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_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
  • 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 http://bitcoinpostage.info/api/create-purchase

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_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] http://bitcoinpostage.info/api/create-purchase

Example output

{
"order_timestamp":"1563268442",
"items":[{
"shipment_id":"shp_...",
"carrier":"usps",
"service":"First",
"from_name":"[name]",
"to_name":"[name]",
"price":"3.12",
"currency":"USD",
"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",
"tracking_no":"944..."
}],
"order_id":"a5e..."
}

Retrieve Purchase

Retrieves a previously created shipping label.

Required fields

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

HTTP request

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

Example request

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

Example output

{
"order_timestamp":"1563268442",
"items":[{
"shipment_id":"shp_...",
"carrier":"usps",
"service":"First",
"from_name":"[name]",
"to_name":"[name]",
"price":"3.12",
"currency":"USD",
"filename":"http:\/\/bitcoinpostage.info\/assets\/labels\/...",
"tracking_no":"944..."
}],
"order_id":"a5e..."
}

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

HTTP request

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

Example request

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

Example output

{
"address":"35G7xaUG91odHPmhsSPGPsQyzVzXeH4sFK",
"id":"6512bd43d9caa6e02c990b0a82652dca",
"amount":"0.00280100",
"timestamp":"1563269563",
"credits":"30",
"purchase_id":"89186"
}

Get Credits

Retrieves your currnet credit balance.

Required fields

  • key: API key
  • secret: API secret

HTTP request

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

Example request

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

Example output

{
"credits":"977"
}