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

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"'

Order

order_name Your internal name for this order. This must be unique.

order_date Date you received this order in UTC format

shipping_billing_code Billing code for shipping method; provided by Bay Photo Lab or retrieved from the api by using the endpoint: /api/v1/shipping_methods.json

return_shipping_id Id for customizing shipping labels and more (optional); provided by Bay Photo Lab

drop_ship Set this to true to remove Bay Photo Lab branding from order

pick_up Set this to true if order is being picked up locally at Bay Photo location

customer Your customer's information; used to ship the order to your customer

products[]

product_id Unique identifier for the product being ordered

qty Number of products you would like produced

photos[]
`image_file_name`	Original file name; often used in communicating about a customers image
`image_source_path`	URL where Bay Photo Lab can pick up the image for order processing
`crop_width / crop_height`	width,height=100 (full image; ie. 100 percentage of image)
`crop_x / crop_y`	Crop: x,y=50 (center)
`node_uid`	uid of the node the photo will be applied to. In most single node products, this is "1"

order_services[]
`service_id`	List of unique identifiers for services to be applied to the entire order

JSON

POST: /api/v1/orders.json

{
  "order_name": "your order name. This must be unique.",
  "order_date": "2015-03-10 03:03:46 UTC",
  "shipping_billing_code": "FEDEX2",
  "return_shipping_id": "",
  "drop_ship": true,
  "customer": {
    "name": "John Doe",
    "email": "john_doe@gmail.com",
    "phone": "123.123.1234",
    "address1": "123 first street",
    "address2": "apt 0",
    "city": "Santa Cruz",
    "state": "CA",
    "country": "US",
    "zip": "95426"
  },
  "products": [
    {
      "product_id": 686,
      "qty": 2,
      "photos":[
        {
          "image_file_name": "original_filename.jpg",
          "image_source_path": "https://www.host.com/1WaPD3YHTwaLJ3y1RhZC",
          "crop_height": "100.0",
          "crop_width": "100.0",
          "crop_x": "50.0",
          "crop_y": "50.0",
          "node_uid": "1"
        }
      ],
      "print_services": [
        {
          "service_id": 3010
        },
        {
          "service_id": 4616
        }
      ]
    }
  ],
  "order_services": [
    {
      "service_id": 100501
    }
  ]
}

`id`	Unique identifier
`name`	Human readable name
`billing_code`	Code that tells us how to ship your order
`tier_prices`	Comma separated list of shipping prices, for shipping methods that have a `tier_type` defined
`tier_type`	For setting tiered shipping prices (ie. tier_type=threshold); dependent on `uses` and `tier_prices`
`tooltip`	Useful for displaying extra information or a more detailed description of the shipping method
`uses`	Specifies what to use to determine the `tier_price`; ie. price of the product

Method 1: Build your own catalog

Method 2: Use our API directly in your app

To implement this method, follow these steps:

Things to consider:

Connecting

Templates

JSON

Options

JSON

Connecting

Order

JSON

Connecting

Shipping Methods

JSON