Note: If you are accessing our API via our IP address, please notice that it has changed. We recommend using https://bitcoinpostage.info/... instead.
Use of HTTP rather than HTTPS will show a '308 - Permanent Redirect' page.

Thank you for using BitcoinPostage

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_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
  • 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
  • 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.

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] 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..."
}

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.
  • 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]&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..."
}

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 https://bitcoinpostage.info/api/retrieve-purchase

Example request

curl -d "key=[API key]&secret=[API secret]&id=[id] https://bitcoinpostage.info/api/retrieve-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..."
}

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 https://bitcoinpostage.info/api/charge-credits

Example request

curl -d "key=[API key]&secret=[API secret]&amount=[amount] https://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 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"
}]