Order

Description

An order object. Orders are created by customers when they complete a purchase checkout or by a studio user creating an order on behalf of a customer.

Properties

Property Description
adjustment 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

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

clientSelectedShippingId

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.

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 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. Any non-numeric characters will be stripped.

digitalDownloadDate 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

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

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 read-only

The identifier for this order, a UUID?.

items

The items belonging to the order.

labApprovedByStudioDate read-only

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

labCatalogId

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

labName nullable read-only

The name of the lab fulfilling this order. Orders can have only one lab, as all lab-fulfilled items in an order will be fulfilled by the same lab.

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 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 orderCustomStatus for description of interaction with that field. @TODO: Determine whether the change history of lab statuses is required.

origin read-only

Describes whether the order was placed by the customer or by the studio.

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 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.

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 read-only

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

salesTaxTitle 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

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.

OpenAPI Schema

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

{
  "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.",
      "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.",
      "type": "string"
    },
    "clientSelectedShippingId": {
      "description": "Shipping option that the client chose at checkout. This field is\nreadOnly in update requests.",
      "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"
    },
    "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.",
      "readOnly": true,
      "type": "string"
    },
    "customerPhone": {
      "description": "The phone number submitted with the order. Any non-numeric characters will be stripped.",
      "nullable": true,
      "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",
      "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+0000",
      "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": {
      "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": {
      "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": {
      "description": "The identifier for this order, a UUID?.",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "readOnly": true,
      "type": "string"
    },
    "items": {
      "description": "The items belonging to the order.",
      "items": {
        "$ref": "#/components/schemas/OrderItem"
      },
      "type": "array"
    },
    "labApprovedByStudioDate": {
      "description": "The date on which this order was approved for processing by lab.",
      "format": "date-time",
      "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.",
      "type": "integer"
    },
    "labName": {
      "description": "The name of the lab fulfilling this order. Orders can have only one\nlab, as all lab-fulfilled items in an order will be fulfilled by the\nsame lab.",
      "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",
      "readOnly": true,
      "type": "string"
    },
    "links": {
      "$ref": "#/components/schemas/Links"
    },
    "orderStatus": {
      "description": "The slug string name of the current status of this order. See\n`orderCustomStatus` 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": "Describes whether the order was placed by the customer or by the\nstudio.",
      "enum": [
        "customer",
        "studio"
      ],
      "readOnly": true,
      "type": "string"
    },
    "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",
      "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"
    },
    "roesOrderId": {
      "description": "The identifier for the order as recognized by ROES, if applicable.",
      "nullable": true,
      "readOnly": true,
      "type": "integer"
    },
    "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.",
      "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.",
      "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.",
      "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",
    "customerPhone",
    "labCatalogId",
    "shippingAddress",
    "billingAddress"
  ],
  "title": "Order",
  "type": "object"
}