The catalog API provides access to your available product catalog, including templates, options, and shipping methods. This API serves the same information as the catalog browser but in a machine-readable format.

Getting data

Method 1 - Build your own catalog

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.

Things to consider:

Connecting

Bay Photo will provide you with an authorization token. This token must be included in the Authorization header of each request to the API. The format of the header is:

Authorization: Token token="TokenValueHere"

Templates

Field Description
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 (BayPhoto 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

Field Description
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[]

Field Description
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" section

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

Field Description
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

Field Description
id Unique identifier
name Human readable name for the product
price Suggested retail price
service_type 1=print, 2=image, 3=order
Field Description
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": []
}

Getting available shipping methods

This is a list of all available shipping methods that you can use when placing an order.

Shipping Method

Field Description
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

JSON

GET /api/v1/shipping_methods.json

[
  {
    "id": 162,
    "billing_code": "FEDEX G_DS",
    "name": "FedEx Ground (1-7 business days)",
    "tier_prices": "",
    "tier_type": "",
    "tooltip": null,
    "uses": "price"
  }
]

GET /api/v1/shipping_methods/163.json

{
  "id": 163,
  "billing_code": "FEDEX XPR_DS",
  "name": "FedEx Express Saver (3 business days)",
  "tier_prices": "",
  "tier_type": "",
  "tooltip": null,
  "uses": "price"
}