Beta Order Collection

Description

A collection of orders.

Properties

Property Description
items

A collection of resources returned in the current result set.

Property Description
adjustment nullable read-only

Amount of adjustment applied to this order. Positive number which is always subtracted from subtotal. Derived from the sum of discount amounts.

balanceDue read-only

The amount of the balance presently due on this order. Should equal the sum of grand total and adjustments minus payments. This is a calculated property. @TODO: remove?

billingAddress required nullable

The billing address for this order.

clientNote nullable

Client submitted note, added by the client/customer when the order was placed.

clientSelectedShippingId nullable

Shipping option that the client chose at checkout. This field is readOnly in update requests.

combinedOrder read-only

Indicates whether this order was created by combining multiple orders.

created read-only

The creation date of this order.

currencyCode read-only

Currency code for the currency all order amounts are expressed in.

currencySymbol read-only

Currency symbol of the currency all order amounts are expressed in.

customStatus nullable

A custom order status provided by the studio

customerCropSelected read-only

Whether this order contains items having a customer defined crop.

customerEmail

The email address of the customer having billing responsibility for this order.

customerName nullable read-only

The name of the customer having billing responsibility for this order. Read-only because it's a property of the customer's address, not the Order object itself.

customerPhone nullable

The phone number submitted with the order.

digitalDownloadDate nullable read-only

Important: this property returns mock data. See example. The date on which the digital order items were downloaded by the customer. Null if fulfillmentType does not contain digital or if the digital items have not yet been downloaded.

digitalSentDate read-only

Important: this property returns mock data. See example. The date on which the digital order items were sent to the customer. Null if fulfillmentType does not contain digital or if the digital items are not yet sent.

digitalStatus nullable read-only

String slug representation of the current digital status of this order. Null if fulfillmentType does not contain digital. 'awaiting-studio' = awaiting studio approval. 'awaiting-payment' = not released because payment is incomplete. 'sent' = the download URL has been emailed to the customer.

eventId nullable deprecated

The identifier for the event this order originates from. This can only be null if the order is part of a combined order. This field is read-only in update requests.

eventName nullable read-only deprecated

The name of the event this order originates from.

fulfillmentTypes read-only

Array of slugs descriptions of the order fulfillment types. An order may have one or more fulfillment types. Determined by the items in the order.

grandTotal read-only

The order grand total value, in the currency selected by the order's currencyCode. Grand total is calculated by adding the item price for each item and item option, subtracting discounts and applying tax. Grand total is fixed to the time when order was placed by the customer.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

isPaid read-only deprecated

The isPaid property is true if the order is fully paid or has been marked as paid through the Studio Panel.

This property is deprecated and may be removed in the future.

itemCount read-only

The number of items on this order.

labApprovedByStudioDate nullable read-only

The date on which this order was approved for processing by lab.

labCatalogId nullable

Identifier of the lab catalog containing the items which comprise this order. This field is readOnly in update requests.

labId nullable read-only

The id of the lab fulfilling the order.

labName nullable read-only deprecated

Deprecated. Please use the lab-catalog link relation to obtain lab information related to this order.

labReceipts read-only

Collection of records of lab receipts of orders.

Property Description
id read-only

The record identifier for the receipt.

labOrderNumber read-only

The order number created by the lab for processing this SP order.

receiptDate read-only

The date when this order was accepted by the lab, the receipt date.

labShipments read-only

Lab shipments associated with this order

Property Description
created read-only

The creation date of this shipment record.

id read-only

The record identifier for the shipment.

labOrderNumber read-only

The order number created by the lab for processing this SP order.

labReference read-only

Text field used by lab to reference the unique identifier the order was submitted to the lab with. Optional reference value that may be used by the lab.

shipDate read-only

The date when this shipment was reported as shipped.

trackingId read-only

The shipment tracking ID, used for tracking the shipment.

trackingUrl read-only

The shipment tracking URL, used for tracking the shipment.

labStatus nullable read-only

The slug string name of the current status of lab fulfilled orders. Null if order is studio-fulfilled. Alternately referred to as lab progress. This is null for any order not having a fulfillmentType containing lab.

labSubmittedDate nullable read-only

The date on which this order's lab fulfilled items were submitted to the lab for fulfillment.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

orderStatus nullable

The slug string name of the current status of this order. See customStatus for description of interaction with that field. @TODO: Determine whether the change history of lab statuses is required.

origin read-only

Indicates whether the order was placed by the studio or by their client.

parentOrderId nullable read-only deprecated

Deprecated. Please use the parent link relation to obtain parent order information related to this order.

paymentStatus read-only

The slug string name of the current payment status of this order. When the Order contains payments having a sum of not more than $0, the paymentStatus is unpaid. When the sum of an order's payments are less than the order's grandTotal, the paymentStatus is 'partially-paid'. When the sum of all order payments equals (or exceeds) the order's grandTotal, the paymentStatus is 'paid'.

pickupAtStudio

Flag indicating whether the order will be picked up at the studio in lieu of being shipped. Applies to self fulfilled items or items drop shipped from lab to studio.

profitReleaseDate nullable read-only

The date and time when order funds were released to the studio. Null if not applicable.

profitReleased read-only

Flag indicating whether the order's profit has been released. Funds are released to studio after 5 days, at which point this will be true. Null if not applicable, only applicable when payment gateway is ShootProof Payments.

retouchRequested beta nullable read-only

Indicates whether the customer has requested retouching on the order.

roesOrderId nullable read-only

The identifier for the order as recognized by ROES, if applicable.

salesTax read-only

Amount of sales tax applied to this order.

salesTaxOnDigitals read-only

Flag indicating whether or not sales tax is applied to digital download items in this order. As indicated on the price sheet at the time the order was placed.

salesTaxOnShipping read-only

Flag indicating whether or not sales tax is applied to the shipping amount. As indicated on the price sheet at the time the order was placed.

salesTaxPercent read-only

The percentage used to calculate sales tax amount.

salesTaxStateId nullable read-only

The 2 character code identifying the US state for which sales tax is being applied.

salesTaxTitle nullable read-only

The human readable string labeling the sales tax amount. This is the sales tax label in use on the price sheet at the time the order was placed.

shippingAddress required nullable

The address this order should be shipped to.

shippingCharge

Amount charged by the studio to the customer for shipping of this order.

studioNote nullable

Studio submitted note, added by the studio owner/user when updating an order.

tags

Tags describing this order.

type

The model type for the response object.

vatNumber nullable read-only

VAT number from the price sheet at the time the order was placed.

vatTotal read-only

The amount of VAT calculated for and applied to this order.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The model type for the list response object.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "description": "A collection of orders.",
  "properties": {
    "items": {
      "description": "A collection of resources returned in the current result set.",
      "items": {
        "description": "An order object. Orders are created by customers when they complete a\npurchase checkout or by a studio user creating an order on behalf of a\ncustomer.",
        "properties": {
          "adjustment": {
            "description": "Amount of adjustment applied to this order. Positive number which is\nalways subtracted from subtotal. Derived from the sum of discount\namounts.",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "balanceDue": {
            "description": "The amount of the balance presently due on this order. Should equal\nthe sum of grand total and adjustments minus payments. This is a\ncalculated property. @TODO: remove?",
            "readOnly": true,
            "type": "number"
          },
          "billingAddress": {
            "allOf": [
              {
                "nullable": true
              },
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "The billing address for this order."
          },
          "clientNote": {
            "description": "Client submitted note, added by the client/customer when the order\nwas placed.",
            "nullable": true,
            "type": "string"
          },
          "clientSelectedShippingId": {
            "description": "Shipping option that the client chose at checkout. This field is\nreadOnly in update requests.",
            "nullable": true,
            "type": "string"
          },
          "combinedOrder": {
            "description": "Indicates whether this order was created by combining multiple\norders.",
            "readOnly": true,
            "type": "boolean"
          },
          "created": {
            "description": "The creation date of this order.",
            "format": "date-time",
            "readOnly": true,
            "type": "string"
          },
          "currencyCode": {
            "description": "Currency code for the currency all order amounts are expressed in.",
            "readOnly": true,
            "type": "string"
          },
          "currencySymbol": {
            "description": "Currency symbol of the currency all order amounts are expressed in.",
            "readOnly": true,
            "type": "string"
          },
          "customStatus": {
            "description": "A custom order status provided by the studio",
            "nullable": true,
            "type": "string"
          },
          "customerCropSelected": {
            "description": "Whether this order contains items having a customer defined crop.",
            "readOnly": true,
            "type": "boolean"
          },
          "customerEmail": {
            "description": "The email address of the customer having billing responsibility for\nthis order.",
            "format": "email",
            "type": "string"
          },
          "customerName": {
            "description": "The name of the customer having billing responsibility for this order.\nRead-only because it's a property of the customer's address, not the Order\nobject itself.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "customerPhone": {
            "description": "The phone number submitted with the order.",
            "nullable": true,
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "digitalDownloadDate": {
            "description": "**Important: this property returns mock data. See example**. The\ndate on which the digital order items were downloaded by the\ncustomer. Null if `fulfillmentType` does not contain `digital` or if\nthe digital items have not yet been downloaded.",
            "example": "null",
            "format": "date-time",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "digitalSentDate": {
            "description": "**Important: this property returns mock data. See example**. The\ndate on which the digital order items were sent to the customer.\nNull if `fulfillmentType` does not contain `digital` or if the\ndigital items are not yet sent.",
            "example": "2018-03-19T02:19:51+00:00",
            "format": "date-time",
            "readOnly": true,
            "type": "string"
          },
          "digitalStatus": {
            "description": "String slug representation of the current digital status of this\norder. Null if `fulfillmentType` does not contain `digital`.\n'awaiting-studio' = awaiting studio approval. 'awaiting-payment' =\nnot released because payment is incomplete. 'sent' = the download\nURL has been emailed to the customer.",
            "enum": [
              "awaiting-studio",
              "awaiting-payment",
              "sent"
            ],
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "eventId": {
            "deprecated": true,
            "description": "The identifier for the event this order originates from. This can\nonly be null if the order is part of a combined order. This field is\nread-only in update requests.",
            "nullable": true,
            "type": "integer"
          },
          "eventName": {
            "deprecated": true,
            "description": "The name of the event this order originates from.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "fulfillmentTypes": {
            "description": "Array of slugs descriptions of the order fulfillment types. An order\nmay have one or more fulfillment types. Determined by the items in\nthe order.",
            "items": {
              "enum": [
                "lab",
                "digital",
                "self"
              ],
              "type": "string"
            },
            "readOnly": true,
            "type": "array"
          },
          "grandTotal": {
            "description": "The order grand total value, in the currency selected by the order's\ncurrencyCode. Grand total is calculated by adding the item price for\neach item and item option, subtracting discounts and applying tax.\nGrand total is fixed to the time when order was placed by the\ncustomer.",
            "readOnly": true,
            "type": "number"
          },
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "isPaid": {
            "deprecated": true,
            "description": "The `isPaid` property is `true` if the order is fully paid or has been\nmarked as paid through the Studio Panel.\n\n*This property is deprecated and may be removed in the future.*",
            "readOnly": true,
            "type": "boolean"
          },
          "itemCount": {
            "description": "The number of items on this order.",
            "readOnly": true,
            "type": "number"
          },
          "labApprovedByStudioDate": {
            "description": "The date on which this order was approved for processing by lab.",
            "format": "date-time",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "labCatalogId": {
            "description": "Identifier of the lab catalog containing the items which comprise\nthis order. This field is readOnly in update requests.",
            "nullable": true,
            "type": "integer"
          },
          "labId": {
            "description": "The id of the lab fulfilling the order.",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "labName": {
            "deprecated": true,
            "description": "*Deprecated.* Please use the `lab-catalog` link relation to obtain lab\ninformation related to this order.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "labReceipts": {
            "description": "Collection of records of lab receipts of orders.",
            "items": {
              "description": "A lab receipt object. Indicates lab receipt of order from studio.",
              "properties": {
                "id": {
                  "description": "The record identifier for the receipt.",
                  "readOnly": true,
                  "type": "integer"
                },
                "labOrderNumber": {
                  "description": "The order number created by the lab for processing this SP\norder.",
                  "readOnly": true,
                  "type": "string"
                },
                "receiptDate": {
                  "description": "The date when this order was accepted by the lab, the receipt\ndate.",
                  "format": "date-time",
                  "readOnly": true,
                  "type": "string"
                }
              },
              "type": "object"
            },
            "readOnly": true,
            "type": "array"
          },
          "labShipments": {
            "description": "Lab shipments associated with this order",
            "items": {
              "description": "A lab shipment object.",
              "properties": {
                "created": {
                  "description": "The creation date of this shipment record.",
                  "format": "date-time",
                  "readOnly": true,
                  "type": "string"
                },
                "id": {
                  "description": "The record identifier for the shipment.",
                  "readOnly": true,
                  "type": "integer"
                },
                "labOrderNumber": {
                  "description": "The order number created by the lab for processing this SP\norder.",
                  "readOnly": true,
                  "type": "string"
                },
                "labReference": {
                  "description": "Text field used by lab to reference the unique identifier the\norder was submitted to the lab with. Optional reference value\nthat may be used by the lab.",
                  "readOnly": true,
                  "type": "string"
                },
                "shipDate": {
                  "description": "The date when this shipment was reported as `shipped`.",
                  "format": "date-time",
                  "readOnly": true,
                  "type": "string"
                },
                "trackingId": {
                  "description": "The shipment tracking ID, used for tracking the shipment.",
                  "readOnly": true,
                  "type": "string"
                },
                "trackingUrl": {
                  "description": "The shipment tracking URL, used for tracking the shipment.",
                  "readOnly": true,
                  "type": "string"
                }
              },
              "type": "object"
            },
            "readOnly": true,
            "type": "array"
          },
          "labStatus": {
            "description": "The slug string name of the current status of lab fulfilled orders.\nNull if order is studio-fulfilled. Alternately referred to as `lab\nprogress`. This is null for any order not having a `fulfillmentType`\ncontaining `lab`.",
            "enum": [
              "pending-copy-of-originals",
              "copying-originals",
              "pending-studio-confirmation",
              "submit-to-lab",
              "submitted-to-lab",
              "lab-received",
              "lab-completed",
              "canceled"
            ],
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "labSubmittedDate": {
            "description": "The date on which this order's lab fulfilled items were submitted to\nthe lab for fulfillment.",
            "format": "date-time",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "links": {
            "$ref": "#/components/schemas/Links"
          },
          "orderStatus": {
            "description": "The slug string name of the current status of this order. See\n`customStatus` for description of interaction with that field.\n@TODO: Determine whether the change history of lab statuses is\nrequired.",
            "enum": [
              "archived",
              "canceled",
              "completed",
              "deleted",
              "new",
              "on-hold",
              "pending",
              "printing",
              "shipped"
            ],
            "nullable": true,
            "type": "string"
          },
          "origin": {
            "description": "Indicates whether the order was placed by the studio or by their client.",
            "enum": [
              "client",
              "studio"
            ],
            "readOnly": true,
            "type": "string"
          },
          "parentOrderId": {
            "deprecated": true,
            "description": "*Deprecated.* Please use the `parent` link relation to obtain parent order\ninformation related to this order.",
            "nullable": true,
            "readOnly": true,
            "type": "number"
          },
          "paymentStatus": {
            "description": "The slug string name of the current payment status of this order.\nWhen the Order contains payments having a sum of not more than $0,\nthe `paymentStatus` is `unpaid`. When the sum of an order's payments\nare less than the order's `grandTotal`, the `paymentStatus` is\n'partially-paid'. When the sum of all order payments equals (or\nexceeds) the order's `grandTotal`, the `paymentStatus` is 'paid'.",
            "enum": [
              "unpaid",
              "partially-paid",
              "paid"
            ],
            "readOnly": true,
            "type": "string"
          },
          "pickupAtStudio": {
            "description": "Flag indicating whether the order will be picked up at the studio in\nlieu of being shipped. Applies to self fulfilled items or items drop\nshipped from lab to studio.",
            "type": "boolean"
          },
          "profitReleaseDate": {
            "description": "The date and time when order funds were released to the studio. Null\nif not applicable.",
            "format": "date-time",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "profitReleased": {
            "description": "Flag indicating whether the order's profit has been released. Funds\nare released to studio after 5 days, at which point this will be\ntrue. Null if not applicable, only applicable when payment gateway\nis ShootProof Payments.",
            "readOnly": true,
            "type": "boolean"
          },
          "retouchRequested": {
            "description": "Indicates whether the customer has requested retouching on the order.",
            "nullable": true,
            "readOnly": true,
            "type": "boolean",
            "x-beta": true,
            "x-internal": true
          },
          "roesOrderId": {
            "description": "The identifier for the order as recognized by ROES, if applicable.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "salesTax": {
            "description": "Amount of sales tax applied to this order.",
            "readOnly": true,
            "type": "number"
          },
          "salesTaxOnDigitals": {
            "description": "Flag indicating whether or not sales tax is applied to digital\ndownload items in this order. As indicated on the price sheet at the\ntime the order was placed.",
            "readOnly": true,
            "type": "boolean"
          },
          "salesTaxOnShipping": {
            "description": "Flag indicating whether or not sales tax is applied to the shipping\namount. As indicated on the price sheet at the time the order was\nplaced.",
            "readOnly": true,
            "type": "boolean"
          },
          "salesTaxPercent": {
            "description": "The percentage used to calculate sales tax amount.",
            "readOnly": true,
            "type": "number"
          },
          "salesTaxStateId": {
            "description": "The 2 character code identifying the US state for which sales tax is\nbeing applied.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "salesTaxTitle": {
            "description": "The human readable string labeling the sales tax amount. This is the\nsales tax label in use on the price sheet at the time the order was\nplaced.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "shippingAddress": {
            "allOf": [
              {
                "nullable": true
              },
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "The address this order should be shipped to."
          },
          "shippingCharge": {
            "description": "Amount charged by the studio to the customer for shipping of this\norder.",
            "type": "number"
          },
          "studioNote": {
            "description": "Studio submitted note, added by the studio owner/user when updating\nan order.",
            "nullable": true,
            "type": "string"
          },
          "tags": {
            "description": "Tags describing this order.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "type": {
            "description": "The model type for the response object.",
            "enum": [
              "order"
            ],
            "type": "string"
          },
          "vatNumber": {
            "description": "VAT number from the price sheet at the time the order was placed.",
            "nullable": true,
            "readOnly": true,
            "type": "string"
          },
          "vatTotal": {
            "description": "The amount of VAT calculated for and applied to this order.",
            "readOnly": true,
            "type": "number"
          }
        },
        "required": [
          "type",
          "brandId",
          "eventId",
          "customerEmail",
          "labCatalogId",
          "shippingAddress",
          "billingAddress"
        ],
        "title": "Order",
        "type": "object",
        "x-beta": true
      },
      "title": "Order",
      "type": "array"
    },
    "links": {
      "$ref": "#/components/schemas/Links"
    },
    "meta": {
      "description": "Metadata describing the current result set.",
      "properties": {
        "currentPage": {
          "description": "The current page of results returned.",
          "type": "integer"
        },
        "rows": {
          "description": "The number of rows returned per page for the current result set.",
          "type": "integer"
        },
        "totalItems": {
          "description": "The total number of items in the result set. This may be\naffected by active search/filter parameters.",
          "type": "integer"
        },
        "totalPages": {
          "description": "The total number of pages in the result set. This is affected by\nthe `rows` parameter (`totalItems / rows == totalPages`).",
          "type": "integer"
        }
      },
      "readOnly": true,
      "type": "object"
    },
    "type": {
      "description": "The model type for the list response object.",
      "enum": [
        "order-collection"
      ],
      "example": "resource-type",
      "title": "Resource Type",
      "type": "string"
    }
  },
  "required": [
    "type",
    "items"
  ],
  "title": "Order Collection",
  "type": "object",
  "x-beta": true
}