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: The second line 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_street2: The second line 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
  • delivery_confirmation: Signature Confirmation.
    List of available: NO_SIGNATURE - No Signature Required. SIGNATURE - Signature Required. ADULT_SIGNATURE - Signature Required by Adult. DO_NOT_SAFE_DROP - Do Not Safe Drop(Canada Post only).

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_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]&delivery_confirmation=[delivery_confirmation] 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":"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
  • delivery_confirmation: Signature Confirmation.
    List of available: NO_SIGNATURE - No Signature Required. SIGNATURE - Signature Required. ADULT_SIGNATURE - Signature Required by Adult. DO_NOT_SAFE_DROP - Do Not Safe Drop(Canada Post only).

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_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]&delivery_confirmation=[delivery_confirmation] https://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..."
}

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

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

Retrack a Stopped 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"
}
]
}
}

Get USPS SCAN Form

Creating USPS SCAN Form for the order.

Required fields

  • key: API key
  • secret: API secret
  • order_id: Order Number

HTTP request

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

Example request

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

Example output

{
"status":"success",
"filename":"http:\/\/bitcoinpostage.info\/assets\/scanforms\/...pdf",
}

Create FedEx Account

After passing the verification process, you will be able to purchase FedEx labels

Required fields

  • key: API key
  • secret: API secret
  • firstname: First Name
  • lastname: Last Name
  • street: Street Address
  • city: City
  • state: State
  • zip: ZIP Code
  • country: Country Code

HTTP request

POST https://bitcoinpostage.info/api/create-fedex-account

Example request

curl -d "key=[API key]&secret=[API secret]&firstname=[First Name]&lastname=[Last Name]&street=[Street Address]&city=[City]&state=[State]&zip=[ZIP Code]&country=[Country Code] https://bitcoinpostage.info/api/create-fedex-account

Example output

{
"status":"success",
"message":"Your FedEx account will be verified shortly"
}