This schema follows the JSON Schema standard, and is used to validate the structure of orders submitted to the Order API v2. It ensures that all required fields are present, that data types are correct, and that certain fields meet specific validation rules.
The schema is a tool used by Bay Photo internally, to automatically validate incoming order JSON. There is no need for integrators to use this schema directly, as the API will automatically validate orders against it. However, integrators may find it useful to answer specific questions about the structure of an order, or to understand the requirements for each property in an order.
The schema is most useful in understanding the particular requirements for each property, like string lengths, number ranges, and other validation rules. Looking at example orders will likely be the easiest way to understand the structure of an order.
There is a schema explorer which allows you to explore the schema in a more user-friendly way, including searching for specific properties and viewing their descriptions. If you encounter any discrepancy between the schema's date of generation (see bottom of page), and the changelog, please notify your account manager and we will update the schema viewer accordingly.
Note: The schema includes a significant number of special properties that are generally intended for internal use by Bay Photo, not by integrators. These properties are never required and are not expected to be used by integrators. Each such property will contain a disclaimer about this in its description.
Any changes to the schema will be documented in the changelog section, and should not be breaking changes. If any extenuating circumstances arise that require potentially breaking changes, they will be communicated in advance.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Bay Photo V2 Order JSON Schema",
"type": "object",
"$defs": {
"address": {
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "Name of a recipient person or business.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"street_address": {
"title": "Street address",
"description": "Up to four street address lines.",
"type": "array",
"minItems": 1,
"maxItems": 4,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"city": {
"title": "City",
"description": "City, village, or locality name.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"state_or_region": {
"title": "State or region",
"description": "State or region name, which may be a full name or an abbreviation.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"postal_code": {
"title": "Postal code",
"type": "string",
"minLength": 1,
"maxLength": 64
},
"country": {
"title": "Country code",
"description": "Two-character ISO 3166-1 alpha-2 country code",
"type": "string",
"enum": [
"AD",
"AE",
"AF",
"AG",
"AI",
"AL",
"AM",
"AO",
"AQ",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BY",
"BZ",
"CA",
"CC",
"CD",
"CF",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CU",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HT",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IR",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KP",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"LY",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"ML",
"MM",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NI",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RU",
"RW",
"SA",
"SB",
"SC",
"SD",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SO",
"SR",
"SS",
"ST",
"SV",
"SX",
"SY",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VE",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"YE",
"YT",
"ZA",
"ZM",
"ZW"
]
}
},
"required": [
"name",
"street_address",
"city",
"state_or_region",
"postal_code",
"country"
]
},
"pricing_configuration": {
"title": "Pricing configuration",
"description": "A configuration object that contains pricing adjustment data to be used when processing the order. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to allow it.",
"type": "object",
"properties": {
"invoice_price": {
"title": "Invoice price",
"description": "A single unit price value for a product/option to use when invoicing this order, in integer cents. Not usable by default, standard integrations will not use this value.",
"type": "integer",
"minimum": 0
},
"price_adjustment_keyword": {
"title": "Price adjustment keyword",
"description": "Price adjustment method to send to Labworks (FKA service_type). Not usable by default, standard integrations will not use this value.",
"type": "string",
"examples": [
"L",
"G",
"M",
"RUSH50",
"METALLIC"
]
}
},
"required": []
},
"item_level_billing_summary": {
"type": "object",
"properties": {
"price": {
"title": "Price",
"description": "Single-quantity price, without discounts, in integer cents.",
"type": "integer",
"minimum": 0
},
"discount": {
"title": "Discount",
"description": "Single-quantity discount amount, in integer cents.",
"type": "integer",
"minimum": 0
},
"sub_total": {
"title": "Sub total",
"description": "Single-quantity price, including discounts, in integer cents.",
"type": "integer",
"minimum": 0
},
"discount_code": {
"title": "Discount code",
"description": "The literal discount code or promo code applied.",
"type": "string",
"examples": [
"METALLUV",
"SUPER20"
]
},
"discount_label": {
"title": "Discount label",
"description": "Displayable 'name' of the discount, usually helpful because the code itself is not helpful in understanding what the true meaning of the discount is.",
"type": "string",
"examples": [
"10%",
"7.5%"
]
}
},
"required": [
"price",
"discount",
"sub_total"
]
}
},
"properties": {
"integrator_identifier": {
"name": "Integrator unique identifier",
"description": "A unique identifier for the order, which has some meaning to the integrator. This is not the same as the order number assigned by Bay Photo. This will be used to identify a duplicate order in the event that an attempt is made to submit the same order more than once. This should almost certainly always be the integrator's order number, assuming that it is unique across all orders submitted by the integrator.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"placed_at": {
"title": "Order placement time & date",
"description": "Time and date at which the order was placed by the customer, in RFC 3339 format (essentially ISO 8601). Must be a time in the past.",
"type": "string",
"format": "date-time"
},
"reference": {
"name": "Reference name or identifier",
"description": "An arbitrary reference name or identifier, which has some meaning to the integrator.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"bay_customer_id": {
"title": "Bay Photo customer ID",
"description": "Used only by Bay Photo for internal purposes, not by 3rd party integrators. Identifies the actual Bay Photo customer placing the order in contexts where the integration/config itself is not enough to do that.",
"type": "string",
"minLength": 1
},
"notification_email": {
"title": "Notification email",
"description": "A recipient email address to which automated notifications should be sent. Example emails would be order confirmations (if applicable) and shipment confirmations. It will _not_ be used for any other purpose, including general customer service communication. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to allow it.",
"type": "string",
"format": "email"
},
"shipping": {
"title": "Shipping information",
"type": "object",
"properties": {
"code": {
"title": "Shipping method code",
"description": "A code that identifies the shipping method to be used for this order. This code is used by Bay Photo to determine the shipping method to use when fulfilling the order.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"account_identifier": {
"title": "Account identifier",
"description": "A unique identifier or code corresponding to an existing shipping account to be used when billing. May be required or optional depending on account configuration.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"return_address_identifier": {
"title": "Return address identifier",
"description": "A unique identifier or code corresponding to a return address to be used when shipping this order. May be required or optional depending on account configuration.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"label_references": {
"title": "Shipping label reference strings",
"description": "Strings which are to be included on printed shipping labels",
"type": "array",
"minItems": 0,
"maxItems": 3
},
"destination_address": {
"title": "Destination address",
"$ref": "#/$defs/address"
}
},
"required": [
"code",
"destination_address"
]
},
"billing_summary": {
"title": "Billing summary",
"description": "A summary of billing information and amounts for the order. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to require it.",
"type": "object",
"properties": {
"tax": {
"title": "Tax amount",
"description": "Tax total in integer cents.",
"type": "integer",
"minimum": 0
},
"shipping": {
"title": "Shipping amount",
"description": "Shipping total in integer cents, including discounts.",
"type": "integer",
"minimum": 0
},
"sub_total": {
"title": "Sub-total amount",
"description": "Sub-total in integer cents, including discounts.",
"type": "integer",
"minimum": 0
},
"total": {
"title": "Total amount",
"description": "Complete total in integer cents, including discounts.",
"type": "integer",
"minimum": 0
},
"promo_code_name": {
"title": "Promo code name",
"description": "The name/code of the promo code applied to the order, if any.",
"type": "string",
"minLength": 1
},
"gift_certificate": {
"title": "Gift certificate",
"description": "Information about a gift certificate used on this order.",
"type": "object",
"properties": {
"name": {
"title": "Gift certificate name",
"description": "The name or code of the gift certificate used.",
"type": "string",
"minLength": 1
},
"amount_used": {
"title": "Gift certificate amount used",
"description": "The amount of the gift certificate used, in integer cents.",
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"amount_used"
]
}
},
"required": [
"tax",
"shipping",
"sub_total",
"total"
]
},
"payment_method": {
"title": "Payment method",
"description": "Details about the payment method to be used to bill this order. Only applicable to integrations/orders which are not pre-paid. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to require it.",
"type": "object",
"properties": {
"display_name": {
"title": "Payment method display name",
"description": "A helpful display name for the payment method.",
"type": "string",
"examples": [
"Apple Pay",
"PayPal",
"Braintree"
]
},
"net_terms": {
"title": "Net terms",
"description": "True if the order is to be billed on net terms.",
"type": "boolean",
"default": false
},
"method_on_file": {
"title": "Bill method on file",
"description": "True if the order is to be billed using the default payment method on file for the customer.",
"type": "boolean",
"default": false
}
},
"required": [
"display_name"
],
"allOf": [
{
"if": {
"properties": {
"net_terms": {
"const": true
}
},
"required": [
"net_terms"
]
},
"then": {
"properties": {
"method_on_file": {
"const": false
}
}
}
},
{
"if": {
"properties": {
"method_on_file": {
"const": true
}
},
"required": [
"method_on_file"
]
},
"then": {
"properties": {
"net_terms": {
"const": false
}
}
}
}
]
},
"images": {
"title": "Images",
"description": "A complete list of all images to be used in the order. Property names are arbitrary unique identifiers for each image, and that property name should be used to identify the image in the order wherever it is intended to be used. Property names are limited to 255 characters.",
"type": "object",
"patternProperties": {
"^.{1,255}$": {
"type": "object",
"properties": {
"filename": {
"description": "The filename of the image, which may be used to identify images within an order. Not a path - do not include slashes or other path separators.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"url": {
"description": "The full URL of the image, exactly as it should be used when the image is being retrieved during order processing. The image's accessibility may be evaluated upon order submission, and as a result it is strongly recommended to ensure the provided URL accepts HEAD requests (which will save bandwidth), and that the URL is usable/accessible _before_ submitting the order.",
"type": "string",
"minLength": 1,
"maxLength": 8192
},
"thumbnail_url": {
"description": "A URL to a thumbnail-sized copy of the image. Preferably, thumbnails should be kept to a maximum of 400 pixels on the longest side. This thumbnail is optional. A thumbnail will be generated internally if not provided, so providing a thumbnail will decrease the wait time for order acceptance. As with full-size image URLs, is strongly recommended to ensure the provided URL usable/accessible _before_ submitting the order.",
"type": "string",
"minLength": 1,
"maxLength": 8192
},
"color_correction": {
"title": "Color correction",
"description": "A flag indicating whether or not color correction should be applied to the image.",
"type": "boolean",
"default": false
}
},
"required": [
"filename",
"url"
]
}
},
"additionalProperties": false
},
"products": {
"title": "Products",
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"name": {
"title": "Product name",
"description": "An optional product name, which may be used to visually identify the product within the order JSON. Including a value here will be helpful to both the integrator and Bay Photo when it comes to identifying products quickly."
},
"code": {
"title": "Product code",
"description": "The code that identifies the product being ordered.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"internal_identifier": {
"name": "Internal identifier",
"description": "An _unique_ identifier for the exact instance of this product, as it exists in this order, which has some meaning to the integrator. This is NOT the same as a product code or SKU - the same product ordered multiple times in the same order, or across multiple orders, should have different internal identifiers. Intended to help an integrator link their internal order data with order data after submission.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"quantity": {
"title": "Quantity",
"type": "integer",
"minimum": 1
},
"size": {
"title": "Product size",
"description": "Some integrators may have a catalog setup which contains 'custom size' products, which do not have a fixed size, and must have their size specified in the order. Including a custom sized product in an order without a size will cause the order to be rejected.",
"type": "object",
"properties": {
"width": {
"title": "Width",
"description": "Product width in inches",
"type": "number",
"minimum": 0,
"multipleOf": 0.25
},
"height": {
"title": "Height",
"description": "Product height in inches",
"type": "number",
"minimum": 0,
"multipleOf": 0.25
}
},
"required": [
"width",
"height"
]
},
"billing_summary": {
"title": "Product billing summary",
"description": "A summary of billing information and amounts for A SINGLE QUANTITY of this product. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to require it.",
"$ref": "#/$defs/item_level_billing_summary"
},
"options": {
"title": "Product options",
"description": "A list of product-level options associated with the product. Depending on the product, one or more options may be required to be specified.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"title": "Option name",
"description": "An optional option name, which may be used to visually identify the option within the order JSON. Including a value here will be helpful to both the integrator and Bay Photo when it comes to identifying options quickly."
},
"code": {
"title": "Option code",
"description": "The code that identifies the option being ordered.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"quantity": {
"title": "Quantity",
"type": "integer",
"minimum": 1
},
"size": {
"title": "Option size",
"description": "Some integrators may have a catalog setup which contains 'custom size' options, which do not have a fixed size, and must have their size specified in the order, either for pricing or production reasons. Including a custom sized option in an order without a size will cause the order to be rejected.",
"type": "object",
"properties": {
"width": {
"title": "Width",
"description": "Option width in inches",
"type": "number",
"minimum": 0,
"multipleOf": 0.25
},
"height": {
"title": "Height",
"description": "Option height in inches",
"type": "number",
"minimum": 0,
"multipleOf": 0.25
}
},
"required": [
"width",
"height"
]
},
"text_content": {
"title": "Text content",
"description": "Options may occasionally require some text content to be specified, i.e. imprinting text.",
"type": "string",
"maxLength": 256
},
"billing_summary": {
"title": "Product option billing summary",
"description": "A summary of billing information and amounts for A SINGLE QUANTITY of this option. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to require it.",
"$ref": "#/$defs/item_level_billing_summary"
},
"pricing_configuration": {
"$ref": "#/$defs/pricing_configuration"
}
},
"required": [
"code",
"quantity"
]
}
},
"images": {
"title": "Images",
"description": "A map between image node IDs and information about what image to apply, and how to apply it.",
"type": "object",
"propertyNames": {
"pattern": "^[0-9]+$"
},
"patternProperties": {
"^[0-9]+$": {
"title": "Product image",
"type": "object",
"properties": {
"image_id": {
"title": "Image unique identifier",
"description": "The unique identifier for the image to be associated with the specified image node. This identifier is determined by the integrator and can be found in the top-level `images` section of the order JSON document. An image can (and should) be reused across multiple products in the same order, if necessary."
},
"job_text": {
"title": "Job text",
"description": "\"Job text\" to be passed directly into DP2 when rendering this image in the product layout for print. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to allow it.",
"type": "string",
"minLength": 1
},
"display_rotation": {
"title": "Display rotation",
"description": "Number of degrees to rotate the entire product for\nright-reading display or rendering, clockwise. Only to\nbe provided if specifically requested by Bay Photo.\nIncluding this JSON property will cause orders to be\nrejected if the integration is not configured to allow\nit. Typically used to correct for the purely-visual\nrotation of certain products in a user-displayed view,\nwhen the natural orientation of a product is different\nfrom the way it is shown to the user. This can impact\ncrop values.\n",
"type": "number",
"minimum": 0,
"default": 0
},
"filter": {
"title": "Image filter",
"description": "An optional image filter/LUT to apply to the image for this product. Only to be provided if specifically allowed by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to allow it.",
"type": "string",
"enum": [
"bw",
"sepia1",
"sepia2"
]
},
"crop": {
"title": "Image crop data",
"description": "Crop information as it relates to the specified image being placed in the specified image node. Cropping is not available to integrators by default. Including this JSON property will cause orders to be rejected if the integration is not configured to allow it. We strongly recommend against using cropping due to its inherent complexity. Provide images which have already been correctly sized for the product being ordered.",
"type": "object",
"properties": {
"type": {
"title": "Crop type",
"description": "The crop type/method to be used.",
"type": "string",
"enum": [
"C",
"F"
]
}
},
"required": [
"type"
],
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "C"
}
}
},
"then": {
"properties": {
"x": {
"title": "Crop x",
"description": "The distance from the left edge of the node to the center of the uncropped image, wherein the magnitude of the number indicates a percentage of the width of the uncropped image, and the sign of the number indicates on which side of the left edge of the node the center of the uncropped image lies. Positive numbers indicate that the center of the image lies to the right of the left edge of the node. Negative numbers indicate that the center of the image lies to the left of the left edge of the node.",
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 100
},
"y": {
"title": "Crop y",
"description": "The distance from the top edge of the node to the center of the uncropped image, wherein the magnitude of the number indicates a percentage of the height of the uncropped image, and the sign of the number indicates on which side of the top edge of the node the center of the uncropped image lies. Positive numbers indicate that the center of the image lies below the top edge of the node. Negative numbers indicate that the center of the image lies above the top edge of the node.",
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 100
},
"width": {
"title": "Crop width",
"description": "Width of the crop area, given as a percentage of the full image's width",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
},
"height": {
"title": "Crop height",
"description": "Height of the crop area, given as a percentage of the full image's height",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100
},
"rotation": {
"title": "Rotation",
"description": "Rotation of the node image in degrees, clockwise",
"type": "number",
"minimum": 0
}
},
"required": [
"x",
"y",
"width",
"height",
"rotation"
]
},
"else": {
"properties": {
"x": false,
"y": false,
"width": false,
"height": false,
"rotation": false
}
}
}
]
}
},
"required": [
"image_id"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"pricing_configuration": {
"$ref": "#/$defs/pricing_configuration"
}
},
"required": [
"code",
"quantity"
]
}
},
"options": {
"title": "Order options",
"description": "A list of order-level options, not associated with any particular product.",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"title": "Option name",
"description": "An optional option name, which may be used to visually identify the option within the order JSON. Including a value here will be helpful to both the integrator and Bay Photo when it comes to identifying options quickly."
},
"code": {
"title": "Option code",
"description": "The code that identifies the option being ordered.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"quantity": {
"title": "Quantity",
"type": "integer",
"minimum": 1
},
"text_content": {
"title": "Text content",
"description": "Options may occasionally require some text content to be specified, i.e. imprinting text.",
"type": "string",
"maxLength": 256
},
"billing_summary": {
"title": "Order option billing summary",
"description": "A summary of billing information and amounts for A SINGLE QUANTITY of this order option. Only to be provided if specifically requested by Bay Photo. Including this JSON property will cause orders to be rejected if the integration is not configured to require it.",
"$ref": "#/$defs/item_level_billing_summary"
},
"pricing_configuration": {
"$ref": "#/$defs/pricing_configuration"
}
},
"required": [
"code",
"quantity"
]
}
}
},
"additionalProperties": false,
"required": [
"integrator_identifier",
"placed_at",
"shipping",
"products"
]
}