Method 1: Build your own catalog

Use our API to build your own catalog by following these steps:
  • Query our /api/v1/templates.json endpoint to retrieve a hierarchical list of all templates
  • Query our /api/v1/options.json?template_id=xxxx endpoint to get a hierarchical list of the options for a template
We recommend parsing our API every-other month to update your catalog, or whenever we notify you of new products.

Method 2: Use our API directly in your app

Alternatively, you can access the catalog directly from your app. The API can return a shallow catalog (only templates in one level of the hierarchy) by adding the flag shallow=true.
To implement this method, follow these steps:
  • Get top-level templates by calling /api/v1/templates.json?shallow=true
  • On template-click request all its dependents /api/v1/templates.json?parent_id=123
  • At this point you can then open a specific template /api/v1/templates/456.json
    • An orderable template will contain a product field with ordering and sizing information
  • Get a template's options /api/v1/options.json?template_id=123
  • Get a specific option /api/v1/options/789.json
    • An orderable option will contain a service field
Things to consider:
  • Some product options are informational only and are identified by the field read_only=true
  • Some product options are not intended for public display and are identified by the field hidden=true
  • So you can set a default template and option in your app, we provide the field default=true
  • The price field is our suggested retail price; you may define your own prices in your app if you wish

Connecting

Bay Photo Lab will provide you with an authorization token. This token must be included in all request headers with the following key/value format.

'Authorization': 'Token token="TokenValueHere"'

Templates

id Unique identifier
default Suggested default selection (true or false)
name Human readable name for the template
name_long Extended description
read_only Identifies the option as a label only and not to be used for placing orders. Useful for displaying alerts about a product.
slug Unique identifier
shipping_group_id For assigning shipping methods (BPL internal use)
parent_id The id of the container/category template that this template belongs to
templates[] Child templates; if the template contains other templates then the template is considered a container/category
product Use the product id when placing an order
id Unique identifier
price Suggested retail price
print_size_x Width of printable area in inches
print_size_y Height of printable area in inches
nodes[] List of available product nodes, ie. image nodes, mask nodes
id Unique identifier
bounds Node position x,y,width,height. These values are in inches.
node_image If node is a mask, an image path will be provided
node_type image=1 or mask=2
option_id Option the node belongs to
template_id Template the node belongs to
sort_order Tells what node to render first for overlay information. Higher numbers are closer to the front.
uid Use this identifier in a photo hash when creating an order. See "Placing Orders" tab

JSON

GET /api/v1/templates.json

[
  {
    "default":false,
    "id":2145,
    "name":"Photo Prints",
    "name_long":"Photo Prints",
    "read_only":false,
    "slug":"print",
    "shipping_group_id":25,
    "templates":[
    {
      "default":false,
      "id":2152,
      "name":"Standout Photo Prints",
      "name_long":"Standout Photo Prints",
      "read_only":false,
      "slug":"StandoutMounts_PhotoPrints",
      "shipping_group_id":"",
      "parent_id":2145,
      "templates":[
      {
        "default":false,
        "id":2153,
        "name":"4x5 Print",
        "name_long":"4x5 Print",
        "read_only":false,
        "slug":"Standout_PhotoPrint_4x5",
        "shipping_group_id":"",
        "parent_id":2152,
        "product":{
          "billing_code":"DR45",
          "id":1975,
          "name":"4x5 Print",
          "price":"0.49",
          "print_size_x":"5.0",
          "print_size_y":"4.0"
        },
        "templates":[]
      },
      ...
      ]
    },
    ...
    ],
    "nodes":[]
  },
  ...
]

GET /api/v1/templates/2153.json


{
  "default":false,
  "id":2153,
  "name":"4x5 Print",
  "name_long":"4x5 Print",
  "read_only":false,
  "slug":"Standout_PhotoPrint_4x5",
  "shipping_group_id":"",
  "templates":[],
  "product":{
    "billing_code":"DR45",
    "id":1975,
    "name":"4x5 Print",
    "price":"0.49",
    "print_size_x":"5.0",
    "print_size_y":"4.0"
  },
  "nodes":[
    {
      "bounds":"0,0,5,4",
      "id":1461,
      "node_image":"",
      "node_type":1,
      "option_id":null,
      "template_id":2153,
      "sort_order": 1,
      "uid": "1"
    }
  ]
}

Options

id Unique identifier
name Human readable name
name_long Extended description
default Suggested default selection (true or false)
disable_ids List of ids of options to disable if this option is chosen
handling_fee BPL internal use
handling_group BPL internal use
hidden If true, the option is not intended for public display
multiple Allows multiple instances of the same option on a product (true or false)
read_only Identifies the option as a label only and not to be used for placing orders. Useful for displaying alerts about a product.
required Identifies a required option
service_type 1=print, 2=image, 3=order
parent_id The id of the option that this option belongs to
service Use the service id with your product when placing an order
id Unique identifier
name Human readable name for the product
price Suggested retail price
service_type 1=print, 2=image, 3=order
options[] Child options; if the option contains other options then the option is considered a container/category

JSON

Query this endpoint by passing a template id. The result is a hierarchical list of options. If the option contains other options then the option is considered a container/category.

GET /api/v1/options.json?template_id=18114

[
  {
    "id":18114,
    "default":false,
    "disable_ids":"",
    "handling_fee":null,
    "handling_group":"",
    "hidden":false,
    "multiple":false,
    "name":"Surface",
    "name_long":"Surface",
    "read_only":false,
    "required":true,
    "service_type":"",
    "options":[
      {
        "id":18115,
        "default":false,
        "disable_ids":"",
        "handling_fee":null,
        "handling_group":"",
        "hidden":false,
        "multiple":false,
        "name":"Lustre",
        "name_long":"Lustre",
        "read_only":false,
        "required":false,
        "service_type":"",
        "parent_id":18114,
        "service":{
          "id":13462,
          "name":"Lustre",
          "price":"0.29",
          "service_type":1
        },
        "nodes":[],
        "options":[]
      },
      ...
    ],
    "nodes":[]
  },
  ...
]

GET /api/v1/options/18115.json

{
  "id":18115,
  "default":false,
  "disable_ids":"",
  "handling_fee":null,
  "handling_group":"",
  "hidden":false,
  "multiple":false,
  "name":"Lustre",
  "name_long":"Lustre",
  "read_only":false,
  "required":false,
  "service_type":"",
  "options":[],
  "service":{
    "id":13462,
    "name":"Lustre",
    "price":"0.29",
    "service_type":1
  },
  "nodes":[]
}