Print Logo

You're using an older browser that we are unable to fully support. Your experience with our site may be less than optimal due to our focus on performance, security and reliability. Consider upgrading your browser if you have problems using our site. Learn More
 

The API for buying, delivering and storing physical precious metals



Run your gold and silver shop using our catalog and fulfillment

{   api.silvergoldbull.com   }






Getting Started

Email api@silvergoldbull.com with your existing customer ID in order to get an API key. Your API key will have access to the same store as your account. To enable the API in multiple countries and languages you can create an account in each store and then generate keys. Advanced services like white labelling and wholesale pricing require volume commitments, please contact us.

This is a JSON REST API. It makes full use of response codes. It is recommended to use a content type header of text/json when posting a JSON body. created_at fields are always UTC.


Just like on our website, orders are binding once placed and guaranteed by your own account. You are making a promise to pay and honor your order commitment. We immediately hedge your order and will lock your order price no matter what happens.



Authentication

Authentication and identification to the Silver Gold Bull API is done by providing an API key in the X-API-KEY header on every request. The API requires that all communication is secured using HTTPS/TLS.


All keys are live. Declarations can be made if you want to test order placement.

Remember to treat your API Keys as passwords and keep them secret. They should not be included in public repositories, client side code, etc.



Rate Limiting

60 requests may be made per 60 second period.



Errors

In the event of a client or server error, the response will contain the standard 4xx or 5xx respectively, accompanied by a well-formed JSON body describing the issue, e.g., a required field was omitted.

Error Object

attribute type specification
message string Human readable description of the problem


Common HTTP Status Codes

code name description
200 OK The request was successful
201 Created The request was successful and one or more resources was created
400 Bad Request Request not processed due to client error
401 Unauthorized Authentication is required and has failed
404 Not Found The requested resource could not be found
405 Method Not Allowed A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST
421 Misdirected Request The request was made to the wrong server
422 Unprocessable Entity The request was well-formed but unable to process the contained instructions
426 Upgrade Required The request must use HTTPS
429 Too Many Requests Too many requests in a 60 second period
500 Internal Server Error Something happened on our side, try again later


List of Currencies

GET   /currencies

View available store currencies.


Request

GET https://api.silvergoldbull.com/v1/currencies

Response

Status: 200 OK
Content-type: application/json
[
   {
      "name" : "Canadian Dollar",
      "id" : "CAD"
   },
   {
      "name" : "US Dollar",
      "id" : "USD"
   },
   {
      "id" : "EUR",
      "name" : "Euro"
   }
]




List of Payment Methods

GET   /payments/method

View available methods and requirements. Use these `method` values to specify the payment type in orders as `payment.method`.


Request

GET https://api.silvergoldbull.com/v1/payments/method

Response

Status: 200 OK
Content-type: application/json
[
   {
      "clearing_days" : 2,
      "id" : "interac-e-transfer",
      "name" : "INTERAC E-Transfer",
      "order_maximum" : 1000,
      "country" : [
         "CA"
      ],
      "currency" : [
         "CAD"
      ]
   },
   {
      "currency" : [
         "CAD",
         "USD",
         "EUR",
         "GBP",
         "AUD",
         "CHF",
         "DKK",
         "HKD",
         "JPY",
         "NOK",
         "NZD",
         "SEK"
      ],
      "order_minimum" : 1000,
      "clearing_days" : 1,
      "id" : "wire-transfer",
      "name" : "Wire Transfer"
   },
   {
      "country" 

 --- shortened ---



List of Shipping Methods

GET   /shipping/method

Use the id for shipping_method field in /create/quote or /create/order.


Request

GET https://api.silvergoldbull.com/v1/shipping/method

Response

Status: 200 OK
Content-type: application/json
[
   {
      "id" : "1YR_STORAGE",
      "name" : "STORAGE 1 year, renewable"
   },
   {
      "name" : "FASTEST insured, signed delivery",
      "id" : "FASTEST_DELIVERY"
   }
]




List of Products

GET   /products

View entire product catalog. Use id in /products to get more detail like prices.


Request

GET https://api.silvergoldbull.com/v1/products

Response

Status: 200 OK
Content-type: application/json
[
   {
      "links" : {
         "self" : {
            "href" : "https://api.silvergoldbull.com/v1/products/3938"
         }
      },
      "id" : "3938",
      "in_stock" : true,
      "name" : "1 oz 2016 Canadian Maple Leaf Silver Coin"
   },
   {
      "in_stock" : true,
      "id" : "3078",
      "links" : {
         "self" : {
            "href" : "https://api.silvergoldbull.com/v1/products/3078"
         }
      },
      "name" : "10 oz New Royal Canadian Mint Silver Bar"
   },
   {
      "links" : {
         "self" : {
            "href" : "https://api.silvergoldbull.com/v1/products/4

 --- shortened ---



Product Pricing and Detail

GET   /products/{id}


input param type example info
id text 1234 Required - use id from /products

Request

GET https://api.silvergoldbull.com/v1/products/{id}

Response

Status: 200 OK
Content-type: application/json
{
   "tax" : [],
   "purity" : "999",
   "image" : "https://xiitec.cachefly.net/media/products/2544/tn-2544-m.png",
   "id" : "2544",
   "prices" : {
      "currency" : "CAD",
      "from" : 1805.41,
      "tiers" : [
         {
            "qty" : 1,
            "price" : 1816.14
         },
         {
            "price" : 1812.12,
            "qty" : 5
         },
         {
            "qty" : 10,
            "price" : 1805.41
         }
      ],
      "to" : 1816.14,
      "cash_discount" : true
   },
   "url" : "https://silvergoldbull.ca/1oz-canadian-gold-maple-leaf-coin",
   "legal_tender" : "CAD 50",
   "mintage" : null,
   "manufacturer" : "Royal Canadian Mint",
   "obverse" : "Maple Leaf",
   "reverse" : "Queen Elizabeth II",
   "country" : "CA",
   "name" : "1 oz Random Year Canadian Maple Leaf Gold Coin",
   "metal_weight_troy_oz" : 1,
   "in_stock" : true,
   "description" : "The Canadian Gold Maple Leaf Coin, the official gold coin of Canada is produced by the Royal Canadian Mint (RCM). \r\nOne of the purest regular issue gold coins in the world, these random year coins will feature a gold content of either 999 or 9999 fineness (24 karats). \r\nYou will receive our choice of dates. \r\nThe gold used is sourced exclusively from Canadian mines.\r\n\r\nFirst issued in 1979, the gold content was measured at 999 until 1983. \r\nOffered in fractions of 1/20 oz, 1/10 oz, 1/4 oz, 1/2 oz and 1 oz, the weight and purity is guaranteed by the government of Canada. \r\nThe coins are legal tender denominated in Canadian Dollars ($1, $5, $10, $20, $50).\r\n\r\nEach of the coins maintain a similar design on both of obverse and reverse. \r\nSome special issues feature colouring, privy marks and other unique attributes.\r\n\r\nThis coin comes with a coin capsule.",
   "days_since_new" : 3780,
   "shape" : "Coin",
   "links" : {
      "self" : {
         "href" : "https://api.silvergoldbull.com/v1/products/2544"
      }
   },
   "qty" : 9999999,
   "total_weight_troy_oz" : 1.2487
}




List of Recent Orders

GET   /orders


Request

GET https://api.silvergoldbull.com/v1/orders

Response

Status: 200 OK
Content-type: application/json
[
   {
      "id" : "1397049587",
      "status" : "canceled",
      "currency" : "CAD",
      "created_at" : "2016-11-04 01:30:23",
      "grand_total" : 343.66,
      "links" : {
         "self" : {
            "href" : "https://api.silvergoldbull.com/v1/orders/1397049587"
         }
      }
   },
   {
      "currency" : "USD",
      "links" : {
         "self" : {
            "href" : "https://api.silvergoldbull.com/v1/orders/1397049331"
         }
      },
      "grand_total" : 492.62,
      "created_at" : "2016-11-02 06:06:11",
      "id" : "1397049331",
      "status" : "canceled"
   },


 --- shortened ---



Order Detail

GET   /orders/{id}

View order detail.


input param type example info
id text 123456789-1 Required - use id from /orders

Request

GET https://api.silvergoldbull.com/v1/orders/{id}

Response

Status: 200 OK
Content-type: application/json
{
   "status" : "canceled",
   "links" : {
      "self" : {
         "href" : "https://api.silvergoldbull.com/v1/orders/1397048909"
      }
   },
   "billing" : {
      "last_name" : "Test",
      "region" : "AB",
      "city" : "CALGARY",
      "company" : null,
      "postcode" : "T2Z 2V3",
      "country" : "Canada",
      "phone" : null,
      "first_name" : "Test",
      "email" : "it@silvergoldbull.com",
      "street" : "123 ABC"
   },
   "shipping_method" : "Free FASTEST",
   "items" : [
      {
         "price" : 443.66,
         "id" : "2706",
         "qty" : 1,
         "tax_amount" : 0,
         "name" : "10 g Sunshine Mint Gold Wafer Bar"
      },
      {
         "name" : "Coin Capsule | 1 oz Silver Coin 38 mm",
         "id" : "2580",
         "tax_amount" : 0,
         "qty" : 1,
         "price" : 1.01
      }
   ],
   "id" : "1397048909",
   "shipping" : {
      "postcode" : "T2Z 2V3",
      "country" : "Canada",
      "company" : null,
      "region" : "AB",
      "last_name" : "Test",
      "city" : "CALGARY",
      "street" : "123 ABC",
      "email" : "it@silvergoldbull.com",
      "first_name" : "Test",
      "phone" : null
   },
   "currency" : "USD",
   "created_at" : "2016-10-30 07:52:33",
   "shipping_amount" : 0,
   "grand_total" : 444.67,
   "tax_amount" : 0
}




Quote Order

POST   /orders/quote

Obtain a live market quote for a new order. If the response is 200 OK then it is valid and the same data can likely be submitted as an order. To guarantee your order being at or below your price, use bid_price. If using bid_price then understand that a successful quote one moment may not submit as an order the next due to market price movements. With or without bid_price you will always get our best price.


input param type example info
billing and shipping.company text Silver Gold Bull Optional
billing and shipping.street text 888 - 3 ST SW Required
billing and shipping.first_name text John Required
billing and shipping.last_name text Smith Required
billing and shipping.city text Calgary Required
billing and shipping.region ISO 3166-2 AB Required for some countries
billing and shipping.postcode text T2P 5C5 Required for some countries
billing and shipping.country ISO 3166-1 alpha-2 CA Required
declaration text TEST Required to be either TEST or PROMISE_TO_PAY
shipping_method text 1YR_STORAGE Required - use id from /shipping/method
payment_method text paypal Required - use id from /payments/method
currency ISO 4217 CAD Required - use id from /currencies
items.id text 2544 Required - use id from /products
items.qty integer 12 Required
items.bid_price decimal 34.92 Optional - only execute if market price is at or below this value in currency

Request

Content-type: text/json
POST https://api.silvergoldbull.com/v1/orders/quote
{
   "currency" : "USD",
   "declaration" : "TEST",
   "payment_method" : "paypal",
   "items" : [
      {
         "bid_price" : 468.37,
         "id" : "2706",
         "qty" : 1
      },
      {
         "bid_price" : 2,
         "id" : "2580",
         "qty" : 1
      }
   ],
   "shipping" : {
      "country" : "CA",
      "phone" : "+1 (403) 668 8648",
      "postcode" : "T2P 5C5",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "email" : "sales@silvergoldbull.com",
      "last_name" : "Smith",
      "region" : "AB",
      "first_name" : "John",
      "city" : "Calgary"
   },
   "billing" : {
      "country" : "CA",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "postcode" : "T2P 5C5",
      "phone" : "+1 (403) 668 8648",
      "region" : "AB",
      "last_name" : "Smith",
      "email" : "sales@silvergoldbull.com",
      "city" : "Calgary",
      "first_name" : "John"
   },
   "shipping_method" : "1YR_STORAGE"
}

Response

Status: 200 OK
Content-type: text/html; charset=utf-8
paypal
Status: 200 OK
Content-Type: application/json

{
   "items" : [
      {
         "tax" : {
            "sum" : {}
         },
         "bid_price" : 468.37,
         "name" : "10 g Sunshine Mint Gold Wafer Bar",
         "id" : "2706",
         "qty" : 1,
         "price" : 450.16
      },
      {
         "tax" : {
            "sum" : {
               "percent" : 5,
               "amount" : "0.05"
            },
            "GST-AB" : {
               "amount" : "0.05",
               "percent" : 5
            }
         },
         "bid_price" : 2,
         "id" : "2580",
         "name" : "Coin Capsule | 1 oz Silver Coin 38 mm",
         "price" : 1.01,
         "qty" : 1
      }
   ],
   "billing" : {
      "postcode" : "T2P 5C5",
      "country" : "CA",
      "email" : "sales@silvergoldbull.com",
      "first_name" : "John",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "city" : "CALGARY",
      "region" : "AB",
      "phone" : "+1 (403) 668 8648",
      "last_name" : "Smith"
   },
   "shipping" : {
      "phone" : "+1 (403) 668 8648",
      "last_name" : "Smith",
      "city" : "CALGARY",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "region" : "AB",
      "email" : "sales@silvergoldbull.com",
      "first_name" : "John",
      "postcode" : "T2P 5C5",
      "country" : "CA"
   },
   "declaration" : "TEST",
   "shipping_description" : "STORAGE 1 year, renewable",
   "shipping_price" : 36.1,
   "grand_total" : 487.32,
   "currency" : "USD",
   "payment_method" : "paypal",
   "shipping_method" : "1YR_STORAGE"
}




Create Order

POST   /orders/create

Create and commit your order. Optionally bid on products so that you only buy them if the price is at or below your price limit. Order is confirmed and binding when the response code is 201 Created and the response JSON includes created_at and the new order id. The order confirmation will be emailed.


input param type example info
billing and shipping.company text Silver Gold Bull Optional
billing and shipping.street text 888 - 3 ST SW Required
billing and shipping.first_name text John Required
billing and shipping.last_name text Smith Required
billing and shipping.city text Calgary Required
billing and shipping.region ISO 3166-2 AB Required for some countries
billing and shipping.postcode text T2P 5C5 Required for some countries
billing and shipping.country ISO 3166-1 alpha-2 CA Required
declaration text TEST Required to be either TEST or PROMISE_TO_PAY
shipping_method text 1YR_STORAGE Required - use id from /shipping/method
payment_method text paypal Required - use id from /payments/method
currency ISO 4217 CAD Required - use id from /currencies
items.id text 2544 Required - use id from /products
items.qty integer 12 Required
items.bid_price decimal 34.92 Optional - only execute if market price is at or below this value in currency

Request

Content-type: text/json
POST https://api.silvergoldbull.com/v1/orders/create
{
   "shipping" : {
      "city" : "Calgary",
      "first_name" : "John",
      "region" : "AB",
      "email" : "sales@silvergoldbull.com",
      "last_name" : "Smith",
      "postcode" : "T2P 5C5",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "phone" : "+1 (403) 668 8648",
      "country" : "CA"
   },
   "shipping_method" : "1YR_STORAGE",
   "billing" : {
      "city" : "Calgary",
      "first_name" : "John",
      "region" : "AB",
      "last_name" : "Smith",
      "email" : "sales@silvergoldbull.com",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "postcode" : "T2P 5C5",
      "phone" : "+1 (403) 668 8648",
      "country" : "CA"
   },
   "declaration" : "TEST",
   "currency" : "USD",
   "items" : [
      {
         "bid_price" : 468.37,
         "qty" : 1,
         "id" : "2706"
      },
      {
         "id" : "2580",
         "qty" : 1,
         "bid_price" : 2
      }
   ],
   "payment_method" : "paypal"
}

Response

Status: 200 OK
Content-type: text/html; charset=utf-8
paypal
Status: 201 Created
Content-Type: application/json

{
   "shipping" : {
      "last_name" : "Smith",
      "first_name" : "John",
      "postcode" : "T2P 5C5",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "country" : "CA",
      "email" : "sales@silvergoldbull.com",
      "region" : "AB",
      "city" : "CALGARY",
      "phone" : "+1 (403) 668 8648"
   },
   "created_at" : "2016-11-05 04:01:26",
   "id" : 9999999999,
   "payment_method" : "paypal",
   "items" : [
      {
         "bid_price" : 468.37,
         "price" : 450.16,
         "id" : "2706",
         "qty" : 1,
         "tax" : {
            "sum" : {}
         },
         "name" : "10 g Sunshine Mint Gold Wafer Bar"
      },
      {
         "name" : "Coin Capsule | 1 oz Silver Coin 38 mm",
         "qty" : 1,
         "tax" : {
            "sum" : {
               "percent" : 5,
               "amount" : "0.05"
            },
            "GST-AB" : {
               "amount" : "0.05",
               "percent" : 5
            }
         },
         "bid_price" : 2,
         "id" : "2580",
         "price" : 1.01
      }
   ],
   "grand_total" : 487.32,
   "shipping_method" : "1YR_STORAGE",
   "currency" : "USD",
   "shipping_description" : "STORAGE 1 year, renewable",
   "declaration" : "TEST",
   "billing" : {
      "email" : "sales@silvergoldbull.com",
      "country" : "CA",
      "street" : "888 - 3 ST SW, 10 FLOOR - WEST TOWER",
      "phone" : "+1 (403) 668 8648",
      "city" : "CALGARY",
      "region" : "AB",
      "last_name" : "Smith",
      "postcode" : "T2P 5C5",
      "first_name" : "John"
   },
   "shipping_price" : 36.1
}