Orders

GET `/orders`

List the organization's orders, newest first by default. Supports search, filtering and cursor pagination.

Requires the orders:read permission.

Query Parameters

limitnumber

The number of records to return.

cursorstring

A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

searchstring

A free-text search term, matched case-insensitively against the record's most identifying fields. Combined with filter using AND.

filterstring

A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, number, totalCents, currencyCode, shippedAt, deliveredAt, cancelledAt, metadata, createdAt, customer.id, customer.email, customer.firstName, customer.lastName, customer.metadata, customer.emailOptOut, customer.emailOptOutSource, customer.createdAt, items.productId, items.productVariantId, tags.name. See Filtering for the syntax.

includestring

A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: importJob, itemsCount, customer, items, tags.

Request

curl \
  "https://api.cascade.dev/orders" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { getOrders } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getOrders()

Request

require "net/http"

uri = URI("https://api.cascade.dev/orders")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/orders",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "siteId": "550e8400-e29b-41d4-a716-446655440000",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "remoteId": "string",
      "number": "string",
      "totalCents": 0,
      "subtotalCents": 0,
      "shippingCents": 0,
      "taxCents": 0,
      "currencyCode": "string",
      "shippedAt": "2025-01-15T09:30:00Z",
      "deliveredAt": "2025-01-15T09:30:00Z",
      "cancelledAt": "2025-01-15T09:30:00Z",
      "metadata": "...",
      "notes": "string",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "importJob": {
        "id": "...",
        "type": "...",
        "action": "...",
        "row": "...",
        "createdAt": "..."
      },
      "itemsCount": 0,
      "customer": {
        "id": "...",
        "email": "...",
        "phone": "...",
        "firstName": "...",
        "lastName": "...",
        "country": "...",
        "birthday": "...",
        "metadata": "...",
        "notes": "...",
        "emailOptOut": "...",
        "emailOptOutAt": "...",
        "emailOptOutSource": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "items": ["..."],
      "tags": ["..."]
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the order."
          },
          "siteId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The site the order was placed on."
          },
          "customerId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The customer who placed the order."
          },
          "remoteId": {
            "type": "string",
            "description": "The order's ID in the store it came from, unique per site. For Shopify this is the Shopify order ID."
          },
          "number": {
            "type": "string",
            "description": "The order number shown to the customer."
          },
          "totalCents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "The order total in the smallest unit of its currency."
          },
          "subtotalCents": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The discounted subtotal excluding shipping and tax, in the smallest unit of the order's currency. Null when the source never provided one."
          },
          "shippingCents": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The shipping charged, in the smallest unit of the order's currency, if known."
          },
          "taxCents": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The tax charged, in the smallest unit of the order's currency, if known."
          },
          "currencyCode": {
            "type": "string",
            "description": "The order's currency, as an ISO 4217 code such as `USD`."
          },
          "shippedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the order shipped, or null if it has not."
          },
          "deliveredAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the order was delivered, or null if it has not been."
          },
          "cancelledAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the order was canceled, or null if it was not."
          },
          "metadata": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
          },
          "notes": {
            "type": "string",
            "description": "Internal notes about the order. Never shown to the customer."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the order was placed."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the order was last changed."
          },
          "importJob": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The import job that wrote the record."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customers",
                      "products",
                      "orders",
                      "wishlists",
                      "reviews",
                      "loyalty-members"
                    ],
                    "description": "What that import's file contained."
                  },
                  "action": {
                    "type": "string",
                    "enum": ["created", "updated"],
                    "description": "Whether the import created this record or updated one that was already there."
                  },
                  "row": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The 1-based row in the import's CSV that became this record, where it is known."
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When that import was started."
                  }
                },
                "required": ["id", "type", "action", "row", "createdAt"],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The import that last wrote this record, or null when no import did."
          },
          "itemsCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many line items the order has."
          },
          "customer": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                "description": "Unique identifier for the customer."
              },
              "email": {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                "description": "The customer's email address, unique within the organization."
              },
              "phone": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's phone number in E.164 format."
              },
              "firstName": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's first name."
              },
              "lastName": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's last name."
              },
              "country": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's country, as an ISO 3166-1 code."
              },
              "birthday": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
                    "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
              },
              "metadata": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
              },
              "notes": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Internal notes about the customer. Never shown to them."
              },
              "emailOptOut": {
                "type": "boolean",
                "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
              },
              "emailOptOutAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "When the opt-out was recorded. Null while the customer is still subscribed."
              },
              "emailOptOutSource": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": ["customer", "merchant", "import", "shopify"],
                    "description": "Where the opt-out came from."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the customer was first created in Cascade."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the customer was last changed."
              }
            },
            "required": [
              "id",
              "email",
              "phone",
              "firstName",
              "lastName",
              "country",
              "birthday",
              "metadata",
              "notes",
              "emailOptOut",
              "emailOptOutAt",
              "emailOptOutSource",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "description": "The customer who placed the order."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "Unique identifier for the line item."
                },
                "productId": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "The product that was bought."
                },
                "productVariantId": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The variant that was bought, or null if the product has no variants."
                },
                "quantity": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991,
                  "description": "How many units of the product this line covers."
                },
                "unitPriceCents": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991,
                  "description": "Price of a single unit, in the smallest unit of the order's currency."
                },
                "product": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                      "description": "Unique identifier for the product."
                    },
                    "slug": {
                      "type": "string",
                      "description": "The product's URL handle, unique within the organization. For Shopify-connected stores this is the Shopify handle, so renaming it there creates a new product here."
                    },
                    "title": {
                      "type": "string",
                      "description": "The product's display name."
                    },
                    "description": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The product's long-form description."
                    },
                    "imageUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "URL of the product's main image."
                    },
                    "url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "URL of the product's page on the storefront, or null if it is not known."
                    },
                    "metadata": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                    },
                    "notes": {
                      "type": "string",
                      "description": "Internal notes about the product. Never shown to customers."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                      "description": "When the product was first created in Cascade."
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                      "description": "When the product was last changed."
                    }
                  },
                  "required": [
                    "id",
                    "slug",
                    "title",
                    "description",
                    "imageUrl",
                    "url",
                    "metadata",
                    "notes",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false,
                  "description": "The product this line refers to."
                },
                "variant": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                          "description": "Unique identifier for the variant."
                        },
                        "slug": {
                          "type": "string",
                          "description": "The variant's handle, unique within its product."
                        },
                        "title": {
                          "type": "string",
                          "description": "The variant's display name, such as its size or color."
                        },
                        "imageUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "URL of the variant's image."
                        },
                        "priceCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": -9007199254740991,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The variant's stored price in cents, or null if it is not known."
                        },
                        "currencyCode": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The currency of `priceCents` as an ISO 4217 code, or null if it is not known."
                        },
                        "available": {
                          "anyOf": [
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Whether the variant can be bought right now, or null if no source has said. Back-in-stock alerts fire on a false to true change, so an unknown availability never triggers one."
                        },
                        "metadata": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                        }
                      },
                      "required": [
                        "id",
                        "slug",
                        "title",
                        "imageUrl",
                        "priceCents",
                        "currencyCode",
                        "available",
                        "metadata"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The variant this line refers to, if any."
                }
              },
              "required": [
                "id",
                "productId",
                "productVariantId",
                "quantity",
                "unitPriceCents",
                "product",
                "variant"
              ],
              "additionalProperties": false
            },
            "description": "The order's line items, with their products and variants resolved."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the tags applied to the order."
          }
        },
        "required": [
          "id",
          "siteId",
          "customerId",
          "remoteId",
          "number",
          "totalCents",
          "subtotalCents",
          "shippingCents",
          "taxCents",
          "currencyCode",
          "shippedAt",
          "deliveredAt",
          "cancelledAt",
          "metadata",
          "notes",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The page of records, in the requested sort order."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass this back as `cursor` to fetch the next page. Null once the last page has been returned."
    }
  },
  "required": ["data", "nextCursor"],
  "additionalProperties": false
}

PATCH `/orders/bulk-update`

Add or remove tags and metadata across every order matching a filter, in one request. Sending no filter applies the changes to every order in the organization.

Requires the orders:write permission.

Costs 5 rate limit tokens instead of the usual one. See Rate limits.

Query Parameters

filterstring

A JSON-encoded filter document selecting the orders to update. Omit it and every order in the organization is updated. See Filtering for the syntax.

searchstring

A free-text search term, matched case-insensitively against the record's most identifying fields. Combined with filter using AND.

Body Parameters

addTagsstring[]

Tag names to add. Tags that do not exist yet are created.

removeTagsstring[]

Tag names to remove.

addMetadataobject

Metadata keys to set, merged onto whatever each order already has.

removeMetadataKeysstring[]

Metadata keys to delete.

Request

curl \
  -X PATCH \
  "https://api.cascade.dev/orders/bulk-update" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "addTags": [
    "string"
  ],
  "removeTags": [
    "string"
  ],
  "addMetadata": "...",
  "removeMetadataKeys": [
    "string"
  ]
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { patchOrdersBulkUpdate } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await patchOrdersBulkUpdate({
  body: {
    addTags: ["string"],
    removeTags: ["string"],
    addMetadata: "...",
    removeMetadataKeys: ["string"],
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/orders/bulk-update")
req = Net::HTTP::Patch.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "addTags": [
      "string"
    ],
    "removeTags": [
      "string"
    ],
    "addMetadata": "...",
    "removeMetadataKeys": [
      "string"
    ]
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "addTags": [
    "string"
  ],
  "removeTags": [
    "string"
  ],
  "addMetadata": "...",
  "removeMetadataKeys": [
    "string"
  ]
}"""

req = Request(
    "https://api.cascade.dev/orders/bulk-update",
    data=body.encode(),
    method="PATCH",
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "count": 0
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many orders the filter matched and updated."
    }
  },
  "required": ["count"],
  "additionalProperties": false
}

POST `/orders/import`

Create or update orders in bulk, matching on remoteId. The customer, site and every product referenced have to exist already, so import those first. Rows whose references don't resolve are skipped and returned in skipped; an order with any item that doesn't resolve is skipped whole, one entry per bad item. Set strict to fail on the first miss instead.

Requires the orders:write permission.

Costs 10 rate limit tokens instead of the usual one. See Rate limits.

Body Parameters

dataobject[]required

The orders to create or update.

strictboolean

When true, a row that references something missing fails the whole import with an error. Off by default: rows whose references don't resolve are skipped and reported in skipped.

earnLoyaltyboolean

Whether newly created orders earn loyalty points and stamps. On by default; turn it off when importing historical orders.

Request

curl \
  -X POST \
  "https://api.cascade.dev/orders/import" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": [
    {
      "site": "string",
      "customer": "[email protected]",
      "remoteId": "string",
      "number": "string",
      "totalCents": 0,
      "subtotalCents": 0,
      "shippingCents": 0,
      "taxCents": 0,
      "currencyCode": "string",
      "shippedAt": "2025-01-15T09:30:00Z",
      "deliveredAt": "2025-01-15T09:30:00Z",
      "cancelledAt": "2025-01-15T09:30:00Z",
      "metadata": "...",
      "items": [
        "..."
      ]
    }
  ],
  "strict": true,
  "earnLoyalty": true
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { postOrdersImport } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postOrdersImport({
  body: {
    data: [
      {
        site: "string",
        customer: "[email protected]",
        remoteId: "string",
        number: "string",
        totalCents: 0,
        subtotalCents: 0,
        shippingCents: 0,
        taxCents: 0,
        currencyCode: "string",
        shippedAt: "2025-01-15T09:30:00Z",
        deliveredAt: "2025-01-15T09:30:00Z",
        cancelledAt: "2025-01-15T09:30:00Z",
        metadata: "...",
        items: ["..."],
      },
    ],
    strict: true,
    earnLoyalty: true,
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/orders/import")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "data": [
      {
        "site": "string",
        "customer": "[email protected]",
        "remoteId": "string",
        "number": "string",
        "totalCents": 0,
        "subtotalCents": 0,
        "shippingCents": 0,
        "taxCents": 0,
        "currencyCode": "string",
        "shippedAt": "2025-01-15T09:30:00Z",
        "deliveredAt": "2025-01-15T09:30:00Z",
        "cancelledAt": "2025-01-15T09:30:00Z",
        "metadata": "...",
        "items": [
          "..."
        ]
      }
    ],
    "strict": true,
    "earnLoyalty": true
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "data": [
    {
      "site": "string",
      "customer": "[email protected]",
      "remoteId": "string",
      "number": "string",
      "totalCents": 0,
      "subtotalCents": 0,
      "shippingCents": 0,
      "taxCents": 0,
      "currencyCode": "string",
      "shippedAt": "2025-01-15T09:30:00Z",
      "deliveredAt": "2025-01-15T09:30:00Z",
      "cancelledAt": "2025-01-15T09:30:00Z",
      "metadata": "...",
      "items": [
        "..."
      ]
    }
  ],
  "strict": true,
  "earnLoyalty": true
}"""

req = Request(
    "https://api.cascade.dev/orders/import",
    data=body.encode(),
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "siteId": "550e8400-e29b-41d4-a716-446655440000",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "remoteId": "string",
      "number": "string",
      "totalCents": 0,
      "subtotalCents": 0,
      "shippingCents": 0,
      "taxCents": 0,
      "currencyCode": "string",
      "shippedAt": "2025-01-15T09:30:00Z",
      "deliveredAt": "2025-01-15T09:30:00Z",
      "cancelledAt": "2025-01-15T09:30:00Z",
      "metadata": "...",
      "notes": "string",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "importJob": {
        "id": "...",
        "type": "...",
        "action": "...",
        "row": "...",
        "createdAt": "..."
      },
      "itemsCount": 0,
      "customer": {
        "id": "...",
        "email": "...",
        "phone": "...",
        "firstName": "...",
        "lastName": "...",
        "country": "...",
        "birthday": "...",
        "metadata": "...",
        "notes": "...",
        "emailOptOut": "...",
        "emailOptOutAt": "...",
        "emailOptOutSource": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "items": ["..."],
      "tags": ["..."]
    }
  ],
  "skipped": [
    {
      "index": 0,
      "message": "string",
      "itemIndex": 0
    }
  ]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the order."
          },
          "siteId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The site the order was placed on."
          },
          "customerId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The customer who placed the order."
          },
          "remoteId": {
            "type": "string",
            "description": "The order's ID in the store it came from, unique per site. For Shopify this is the Shopify order ID."
          },
          "number": {
            "type": "string",
            "description": "The order number shown to the customer."
          },
          "totalCents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "The order total in the smallest unit of its currency."
          },
          "subtotalCents": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The discounted subtotal excluding shipping and tax, in the smallest unit of the order's currency. Null when the source never provided one."
          },
          "shippingCents": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The shipping charged, in the smallest unit of the order's currency, if known."
          },
          "taxCents": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ],
            "description": "The tax charged, in the smallest unit of the order's currency, if known."
          },
          "currencyCode": {
            "type": "string",
            "description": "The order's currency, as an ISO 4217 code such as `USD`."
          },
          "shippedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the order shipped, or null if it has not."
          },
          "deliveredAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the order was delivered, or null if it has not been."
          },
          "cancelledAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the order was canceled, or null if it was not."
          },
          "metadata": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
          },
          "notes": {
            "type": "string",
            "description": "Internal notes about the order. Never shown to the customer."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the order was placed."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the order was last changed."
          },
          "importJob": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The import job that wrote the record."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customers",
                      "products",
                      "orders",
                      "wishlists",
                      "reviews",
                      "loyalty-members"
                    ],
                    "description": "What that import's file contained."
                  },
                  "action": {
                    "type": "string",
                    "enum": ["created", "updated"],
                    "description": "Whether the import created this record or updated one that was already there."
                  },
                  "row": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The 1-based row in the import's CSV that became this record, where it is known."
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When that import was started."
                  }
                },
                "required": ["id", "type", "action", "row", "createdAt"],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The import that last wrote this record, or null when no import did."
          },
          "itemsCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many line items the order has."
          },
          "customer": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                "description": "Unique identifier for the customer."
              },
              "email": {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
                "description": "The customer's email address, unique within the organization."
              },
              "phone": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's phone number in E.164 format."
              },
              "firstName": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's first name."
              },
              "lastName": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's last name."
              },
              "country": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's country, as an ISO 3166-1 code."
              },
              "birthday": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
                    "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
              },
              "metadata": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
              },
              "notes": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Internal notes about the customer. Never shown to them."
              },
              "emailOptOut": {
                "type": "boolean",
                "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
              },
              "emailOptOutAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "When the opt-out was recorded. Null while the customer is still subscribed."
              },
              "emailOptOutSource": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": ["customer", "merchant", "import", "shopify"],
                    "description": "Where the opt-out came from."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the customer was first created in Cascade."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the customer was last changed."
              }
            },
            "required": [
              "id",
              "email",
              "phone",
              "firstName",
              "lastName",
              "country",
              "birthday",
              "metadata",
              "notes",
              "emailOptOut",
              "emailOptOutAt",
              "emailOptOutSource",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "description": "The customer who placed the order."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "Unique identifier for the line item."
                },
                "productId": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                  "description": "The product that was bought."
                },
                "productVariantId": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The variant that was bought, or null if the product has no variants."
                },
                "quantity": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991,
                  "description": "How many units of the product this line covers."
                },
                "unitPriceCents": {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991,
                  "description": "Price of a single unit, in the smallest unit of the order's currency."
                },
                "product": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                      "description": "Unique identifier for the product."
                    },
                    "slug": {
                      "type": "string",
                      "description": "The product's URL handle, unique within the organization. For Shopify-connected stores this is the Shopify handle, so renaming it there creates a new product here."
                    },
                    "title": {
                      "type": "string",
                      "description": "The product's display name."
                    },
                    "description": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The product's long-form description."
                    },
                    "imageUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "URL of the product's main image."
                    },
                    "url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "URL of the product's page on the storefront, or null if it is not known."
                    },
                    "metadata": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                    },
                    "notes": {
                      "type": "string",
                      "description": "Internal notes about the product. Never shown to customers."
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                      "description": "When the product was first created in Cascade."
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                      "description": "When the product was last changed."
                    }
                  },
                  "required": [
                    "id",
                    "slug",
                    "title",
                    "description",
                    "imageUrl",
                    "url",
                    "metadata",
                    "notes",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false,
                  "description": "The product this line refers to."
                },
                "variant": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                          "description": "Unique identifier for the variant."
                        },
                        "slug": {
                          "type": "string",
                          "description": "The variant's handle, unique within its product."
                        },
                        "title": {
                          "type": "string",
                          "description": "The variant's display name, such as its size or color."
                        },
                        "imageUrl": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "URL of the variant's image."
                        },
                        "priceCents": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": -9007199254740991,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The variant's stored price in cents, or null if it is not known."
                        },
                        "currencyCode": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The currency of `priceCents` as an ISO 4217 code, or null if it is not known."
                        },
                        "available": {
                          "anyOf": [
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Whether the variant can be bought right now, or null if no source has said. Back-in-stock alerts fire on a false to true change, so an unknown availability never triggers one."
                        },
                        "metadata": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                        }
                      },
                      "required": [
                        "id",
                        "slug",
                        "title",
                        "imageUrl",
                        "priceCents",
                        "currencyCode",
                        "available",
                        "metadata"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The variant this line refers to, if any."
                }
              },
              "required": [
                "id",
                "productId",
                "productVariantId",
                "quantity",
                "unitPriceCents",
                "product",
                "variant"
              ],
              "additionalProperties": false
            },
            "description": "The order's line items, with their products and variants resolved."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the tags applied to the order."
          }
        },
        "required": [
          "id",
          "siteId",
          "customerId",
          "remoteId",
          "number",
          "totalCents",
          "subtotalCents",
          "shippingCents",
          "taxCents",
          "currencyCode",
          "shippedAt",
          "deliveredAt",
          "cancelledAt",
          "metadata",
          "notes",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The imported orders, as they now stand."
    },
    "skipped": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Position of the row in the batch you sent."
          },
          "message": {
            "type": "string",
            "description": "Why the row could not be imported."
          },
          "itemIndex": {
            "description": "Zero-based position of the item that failed within the row's items. Absent when the failure was on the row itself.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": ["index", "message"],
        "additionalProperties": false
      },
      "description": "The rows that could not be imported, and why."
    }
  },
  "required": ["data", "skipped"],
  "additionalProperties": false
}

GET `/orders/{id}`

Get a single order by ID.

Requires the orders:read permission.

Path Parameters

idstring (uuid)required

The ID of the order.

Query Parameters

includestring

A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: importJob, itemsCount, customer, items, tags.

Request

curl \
  "https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { getOrdersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getOrdersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "remoteId": "string",
  "number": "string",
  "totalCents": 0,
  "subtotalCents": 0,
  "shippingCents": 0,
  "taxCents": 0,
  "currencyCode": "string",
  "shippedAt": "2025-01-15T09:30:00Z",
  "deliveredAt": "2025-01-15T09:30:00Z",
  "cancelledAt": "2025-01-15T09:30:00Z",
  "metadata": "...",
  "notes": "string",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "importJob": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customers",
    "action": "created",
    "row": 0,
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "itemsCount": 0,
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "birthday": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "productVariantId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 0,
      "unitPriceCents": 0,
      "product": {
        "id": "...",
        "slug": "...",
        "title": "...",
        "description": "...",
        "imageUrl": "...",
        "url": "...",
        "metadata": "...",
        "notes": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "variant": {
        "id": "...",
        "slug": "...",
        "title": "...",
        "imageUrl": "...",
        "priceCents": "...",
        "currencyCode": "...",
        "available": "...",
        "metadata": "..."
      }
    }
  ],
  "tags": ["string"]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the order."
    },
    "siteId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The site the order was placed on."
    },
    "customerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The customer who placed the order."
    },
    "remoteId": {
      "type": "string",
      "description": "The order's ID in the store it came from, unique per site. For Shopify this is the Shopify order ID."
    },
    "number": {
      "type": "string",
      "description": "The order number shown to the customer."
    },
    "totalCents": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The order total in the smallest unit of its currency."
    },
    "subtotalCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The discounted subtotal excluding shipping and tax, in the smallest unit of the order's currency. Null when the source never provided one."
    },
    "shippingCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The shipping charged, in the smallest unit of the order's currency, if known."
    },
    "taxCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The tax charged, in the smallest unit of the order's currency, if known."
    },
    "currencyCode": {
      "type": "string",
      "description": "The order's currency, as an ISO 4217 code such as `USD`."
    },
    "shippedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order shipped, or null if it has not."
    },
    "deliveredAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order was delivered, or null if it has not been."
    },
    "cancelledAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order was canceled, or null if it was not."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "notes": {
      "type": "string",
      "description": "Internal notes about the order. Never shown to the customer."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the order was placed."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the order was last changed."
    },
    "importJob": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
              "description": "The import job that wrote the record."
            },
            "type": {
              "type": "string",
              "enum": [
                "customers",
                "products",
                "orders",
                "wishlists",
                "reviews",
                "loyalty-members"
              ],
              "description": "What that import's file contained."
            },
            "action": {
              "type": "string",
              "enum": ["created", "updated"],
              "description": "Whether the import created this record or updated one that was already there."
            },
            "row": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ],
              "description": "The 1-based row in the import's CSV that became this record, where it is known."
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
              "description": "When that import was started."
            }
          },
          "required": ["id", "type", "action", "row", "createdAt"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The import that last wrote this record, or null when no import did."
    },
    "itemsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many line items the order has."
    },
    "customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Unique identifier for the customer."
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The customer's email address, unique within the organization."
        },
        "phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's phone number in E.164 format."
        },
        "firstName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's first name."
        },
        "lastName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's last name."
        },
        "country": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's country, as an ISO 3166-1 code."
        },
        "birthday": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
              "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
        },
        "metadata": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          },
          "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
        },
        "notes": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Internal notes about the customer. Never shown to them."
        },
        "emailOptOut": {
          "type": "boolean",
          "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
        },
        "emailOptOutAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the opt-out was recorded. Null while the customer is still subscribed."
        },
        "emailOptOutSource": {
          "anyOf": [
            {
              "type": "string",
              "enum": ["customer", "merchant", "import", "shopify"],
              "description": "Where the opt-out came from."
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the customer was first created in Cascade."
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the customer was last changed."
        }
      },
      "required": [
        "id",
        "email",
        "phone",
        "firstName",
        "lastName",
        "country",
        "birthday",
        "metadata",
        "notes",
        "emailOptOut",
        "emailOptOutAt",
        "emailOptOutSource",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false,
      "description": "The customer who placed the order."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the line item."
          },
          "productId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The product that was bought."
          },
          "productVariantId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ],
            "description": "The variant that was bought, or null if the product has no variants."
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many units of the product this line covers."
          },
          "unitPriceCents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Price of a single unit, in the smallest unit of the order's currency."
          },
          "product": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                "description": "Unique identifier for the product."
              },
              "slug": {
                "type": "string",
                "description": "The product's URL handle, unique within the organization. For Shopify-connected stores this is the Shopify handle, so renaming it there creates a new product here."
              },
              "title": {
                "type": "string",
                "description": "The product's display name."
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The product's long-form description."
              },
              "imageUrl": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "URL of the product's main image."
              },
              "url": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "URL of the product's page on the storefront, or null if it is not known."
              },
              "metadata": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
              },
              "notes": {
                "type": "string",
                "description": "Internal notes about the product. Never shown to customers."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the product was first created in Cascade."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the product was last changed."
              }
            },
            "required": [
              "id",
              "slug",
              "title",
              "description",
              "imageUrl",
              "url",
              "metadata",
              "notes",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "description": "The product this line refers to."
          },
          "variant": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "Unique identifier for the variant."
                  },
                  "slug": {
                    "type": "string",
                    "description": "The variant's handle, unique within its product."
                  },
                  "title": {
                    "type": "string",
                    "description": "The variant's display name, such as its size or color."
                  },
                  "imageUrl": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "URL of the variant's image."
                  },
                  "priceCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The variant's stored price in cents, or null if it is not known."
                  },
                  "currencyCode": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The currency of `priceCents` as an ISO 4217 code, or null if it is not known."
                  },
                  "available": {
                    "anyOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Whether the variant can be bought right now, or null if no source has said. Back-in-stock alerts fire on a false to true change, so an unknown availability never triggers one."
                  },
                  "metadata": {
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                  }
                },
                "required": [
                  "id",
                  "slug",
                  "title",
                  "imageUrl",
                  "priceCents",
                  "currencyCode",
                  "available",
                  "metadata"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The variant this line refers to, if any."
          }
        },
        "required": [
          "id",
          "productId",
          "productVariantId",
          "quantity",
          "unitPriceCents",
          "product",
          "variant"
        ],
        "additionalProperties": false
      },
      "description": "The order's line items, with their products and variants resolved."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the tags applied to the order."
    }
  },
  "required": [
    "id",
    "siteId",
    "customerId",
    "remoteId",
    "number",
    "totalCents",
    "subtotalCents",
    "shippingCents",
    "taxCents",
    "currencyCode",
    "shippedAt",
    "deliveredAt",
    "cancelledAt",
    "metadata",
    "notes",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The requested order."
}

PATCH `/orders/{id}`

Update an order's metadata, notes or tags. Commercial fields such as the total and fulfillment dates come from the store and cannot be edited here. Triggers the order.updated webhook.

Requires the orders:write permission.

Path Parameters

idstring (uuid)required

The ID of the order to update.

Body Parameters

metadataobject

Replaces the order's metadata wholesale. Omit to leave it alone.

notesstring

Internal notes about the order.

tagsstring[]

The order's full set of tag names. Omit to leave the tags alone.

Request

curl \
  -X PATCH \
  "https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": "...",
  "notes": "string",
  "tags": [
    "string"
  ]
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { patchOrdersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await patchOrdersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
  body: {
    metadata: "...",
    notes: "string",
    tags: ["string"],
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Patch.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "metadata": "...",
    "notes": "string",
    "tags": [
      "string"
    ]
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "metadata": "...",
  "notes": "string",
  "tags": [
    "string"
  ]
}"""

req = Request(
    "https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000",
    data=body.encode(),
    method="PATCH",
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "remoteId": "string",
  "number": "string",
  "totalCents": 0,
  "subtotalCents": 0,
  "shippingCents": 0,
  "taxCents": 0,
  "currencyCode": "string",
  "shippedAt": "2025-01-15T09:30:00Z",
  "deliveredAt": "2025-01-15T09:30:00Z",
  "cancelledAt": "2025-01-15T09:30:00Z",
  "metadata": "...",
  "notes": "string",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "importJob": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customers",
    "action": "created",
    "row": 0,
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "itemsCount": 0,
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "birthday": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "productVariantId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 0,
      "unitPriceCents": 0,
      "product": {
        "id": "...",
        "slug": "...",
        "title": "...",
        "description": "...",
        "imageUrl": "...",
        "url": "...",
        "metadata": "...",
        "notes": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "variant": {
        "id": "...",
        "slug": "...",
        "title": "...",
        "imageUrl": "...",
        "priceCents": "...",
        "currencyCode": "...",
        "available": "...",
        "metadata": "..."
      }
    }
  ],
  "tags": ["string"]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the order."
    },
    "siteId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The site the order was placed on."
    },
    "customerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The customer who placed the order."
    },
    "remoteId": {
      "type": "string",
      "description": "The order's ID in the store it came from, unique per site. For Shopify this is the Shopify order ID."
    },
    "number": {
      "type": "string",
      "description": "The order number shown to the customer."
    },
    "totalCents": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The order total in the smallest unit of its currency."
    },
    "subtotalCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The discounted subtotal excluding shipping and tax, in the smallest unit of the order's currency. Null when the source never provided one."
    },
    "shippingCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The shipping charged, in the smallest unit of the order's currency, if known."
    },
    "taxCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The tax charged, in the smallest unit of the order's currency, if known."
    },
    "currencyCode": {
      "type": "string",
      "description": "The order's currency, as an ISO 4217 code such as `USD`."
    },
    "shippedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order shipped, or null if it has not."
    },
    "deliveredAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order was delivered, or null if it has not been."
    },
    "cancelledAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order was canceled, or null if it was not."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "notes": {
      "type": "string",
      "description": "Internal notes about the order. Never shown to the customer."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the order was placed."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the order was last changed."
    },
    "importJob": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
              "description": "The import job that wrote the record."
            },
            "type": {
              "type": "string",
              "enum": [
                "customers",
                "products",
                "orders",
                "wishlists",
                "reviews",
                "loyalty-members"
              ],
              "description": "What that import's file contained."
            },
            "action": {
              "type": "string",
              "enum": ["created", "updated"],
              "description": "Whether the import created this record or updated one that was already there."
            },
            "row": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ],
              "description": "The 1-based row in the import's CSV that became this record, where it is known."
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
              "description": "When that import was started."
            }
          },
          "required": ["id", "type", "action", "row", "createdAt"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The import that last wrote this record, or null when no import did."
    },
    "itemsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many line items the order has."
    },
    "customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Unique identifier for the customer."
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The customer's email address, unique within the organization."
        },
        "phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's phone number in E.164 format."
        },
        "firstName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's first name."
        },
        "lastName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's last name."
        },
        "country": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's country, as an ISO 3166-1 code."
        },
        "birthday": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
              "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
        },
        "metadata": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          },
          "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
        },
        "notes": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Internal notes about the customer. Never shown to them."
        },
        "emailOptOut": {
          "type": "boolean",
          "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
        },
        "emailOptOutAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the opt-out was recorded. Null while the customer is still subscribed."
        },
        "emailOptOutSource": {
          "anyOf": [
            {
              "type": "string",
              "enum": ["customer", "merchant", "import", "shopify"],
              "description": "Where the opt-out came from."
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the customer was first created in Cascade."
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the customer was last changed."
        }
      },
      "required": [
        "id",
        "email",
        "phone",
        "firstName",
        "lastName",
        "country",
        "birthday",
        "metadata",
        "notes",
        "emailOptOut",
        "emailOptOutAt",
        "emailOptOutSource",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false,
      "description": "The customer who placed the order."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the line item."
          },
          "productId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The product that was bought."
          },
          "productVariantId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ],
            "description": "The variant that was bought, or null if the product has no variants."
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many units of the product this line covers."
          },
          "unitPriceCents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Price of a single unit, in the smallest unit of the order's currency."
          },
          "product": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                "description": "Unique identifier for the product."
              },
              "slug": {
                "type": "string",
                "description": "The product's URL handle, unique within the organization. For Shopify-connected stores this is the Shopify handle, so renaming it there creates a new product here."
              },
              "title": {
                "type": "string",
                "description": "The product's display name."
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The product's long-form description."
              },
              "imageUrl": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "URL of the product's main image."
              },
              "url": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "URL of the product's page on the storefront, or null if it is not known."
              },
              "metadata": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
              },
              "notes": {
                "type": "string",
                "description": "Internal notes about the product. Never shown to customers."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the product was first created in Cascade."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the product was last changed."
              }
            },
            "required": [
              "id",
              "slug",
              "title",
              "description",
              "imageUrl",
              "url",
              "metadata",
              "notes",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "description": "The product this line refers to."
          },
          "variant": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "Unique identifier for the variant."
                  },
                  "slug": {
                    "type": "string",
                    "description": "The variant's handle, unique within its product."
                  },
                  "title": {
                    "type": "string",
                    "description": "The variant's display name, such as its size or color."
                  },
                  "imageUrl": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "URL of the variant's image."
                  },
                  "priceCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The variant's stored price in cents, or null if it is not known."
                  },
                  "currencyCode": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The currency of `priceCents` as an ISO 4217 code, or null if it is not known."
                  },
                  "available": {
                    "anyOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Whether the variant can be bought right now, or null if no source has said. Back-in-stock alerts fire on a false to true change, so an unknown availability never triggers one."
                  },
                  "metadata": {
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                  }
                },
                "required": [
                  "id",
                  "slug",
                  "title",
                  "imageUrl",
                  "priceCents",
                  "currencyCode",
                  "available",
                  "metadata"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The variant this line refers to, if any."
          }
        },
        "required": [
          "id",
          "productId",
          "productVariantId",
          "quantity",
          "unitPriceCents",
          "product",
          "variant"
        ],
        "additionalProperties": false
      },
      "description": "The order's line items, with their products and variants resolved."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the tags applied to the order."
    }
  },
  "required": [
    "id",
    "siteId",
    "customerId",
    "remoteId",
    "number",
    "totalCents",
    "subtotalCents",
    "shippingCents",
    "taxCents",
    "currencyCode",
    "shippedAt",
    "deliveredAt",
    "cancelledAt",
    "metadata",
    "notes",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The updated order."
}

DELETE `/orders/{id}`

Delete an order along with its line items and tags. Triggers the order.deleted webhook.

Requires the orders:write permission.

Path Parameters

idstring (uuid)required

The ID of the order to delete.

Request

curl \
  -X DELETE \
  "https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { deleteOrdersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteOrdersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Delete.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/orders/550e8400-e29b-41d4-a716-446655440000",
    method="DELETE",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "remoteId": "string",
  "number": "string",
  "totalCents": 0,
  "subtotalCents": 0,
  "shippingCents": 0,
  "taxCents": 0,
  "currencyCode": "string",
  "shippedAt": "2025-01-15T09:30:00Z",
  "deliveredAt": "2025-01-15T09:30:00Z",
  "cancelledAt": "2025-01-15T09:30:00Z",
  "metadata": "...",
  "notes": "string",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "importJob": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customers",
    "action": "created",
    "row": 0,
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "itemsCount": 0,
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "birthday": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "productVariantId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 0,
      "unitPriceCents": 0,
      "product": {
        "id": "...",
        "slug": "...",
        "title": "...",
        "description": "...",
        "imageUrl": "...",
        "url": "...",
        "metadata": "...",
        "notes": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "variant": {
        "id": "...",
        "slug": "...",
        "title": "...",
        "imageUrl": "...",
        "priceCents": "...",
        "currencyCode": "...",
        "available": "...",
        "metadata": "..."
      }
    }
  ],
  "tags": ["string"]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the order."
    },
    "siteId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The site the order was placed on."
    },
    "customerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The customer who placed the order."
    },
    "remoteId": {
      "type": "string",
      "description": "The order's ID in the store it came from, unique per site. For Shopify this is the Shopify order ID."
    },
    "number": {
      "type": "string",
      "description": "The order number shown to the customer."
    },
    "totalCents": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The order total in the smallest unit of its currency."
    },
    "subtotalCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The discounted subtotal excluding shipping and tax, in the smallest unit of the order's currency. Null when the source never provided one."
    },
    "shippingCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The shipping charged, in the smallest unit of the order's currency, if known."
    },
    "taxCents": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ],
      "description": "The tax charged, in the smallest unit of the order's currency, if known."
    },
    "currencyCode": {
      "type": "string",
      "description": "The order's currency, as an ISO 4217 code such as `USD`."
    },
    "shippedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order shipped, or null if it has not."
    },
    "deliveredAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order was delivered, or null if it has not been."
    },
    "cancelledAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the order was canceled, or null if it was not."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "notes": {
      "type": "string",
      "description": "Internal notes about the order. Never shown to the customer."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the order was placed."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the order was last changed."
    },
    "importJob": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
              "description": "The import job that wrote the record."
            },
            "type": {
              "type": "string",
              "enum": [
                "customers",
                "products",
                "orders",
                "wishlists",
                "reviews",
                "loyalty-members"
              ],
              "description": "What that import's file contained."
            },
            "action": {
              "type": "string",
              "enum": ["created", "updated"],
              "description": "Whether the import created this record or updated one that was already there."
            },
            "row": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ],
              "description": "The 1-based row in the import's CSV that became this record, where it is known."
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
              "description": "When that import was started."
            }
          },
          "required": ["id", "type", "action", "row", "createdAt"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The import that last wrote this record, or null when no import did."
    },
    "itemsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many line items the order has."
    },
    "customer": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
          "description": "Unique identifier for the customer."
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "The customer's email address, unique within the organization."
        },
        "phone": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's phone number in E.164 format."
        },
        "firstName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's first name."
        },
        "lastName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's last name."
        },
        "country": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's country, as an ISO 3166-1 code."
        },
        "birthday": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
              "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
            },
            {
              "type": "null"
            }
          ],
          "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
        },
        "metadata": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "string"
          },
          "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
        },
        "notes": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Internal notes about the customer. Never shown to them."
        },
        "emailOptOut": {
          "type": "boolean",
          "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
        },
        "emailOptOutAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the opt-out was recorded. Null while the customer is still subscribed."
        },
        "emailOptOutSource": {
          "anyOf": [
            {
              "type": "string",
              "enum": ["customer", "merchant", "import", "shopify"],
              "description": "Where the opt-out came from."
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the customer was first created in Cascade."
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "When the customer was last changed."
        }
      },
      "required": [
        "id",
        "email",
        "phone",
        "firstName",
        "lastName",
        "country",
        "birthday",
        "metadata",
        "notes",
        "emailOptOut",
        "emailOptOutAt",
        "emailOptOutSource",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false,
      "description": "The customer who placed the order."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the line item."
          },
          "productId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The product that was bought."
          },
          "productVariantId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              {
                "type": "null"
              }
            ],
            "description": "The variant that was bought, or null if the product has no variants."
          },
          "quantity": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many units of the product this line covers."
          },
          "unitPriceCents": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Price of a single unit, in the smallest unit of the order's currency."
          },
          "product": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                "description": "Unique identifier for the product."
              },
              "slug": {
                "type": "string",
                "description": "The product's URL handle, unique within the organization. For Shopify-connected stores this is the Shopify handle, so renaming it there creates a new product here."
              },
              "title": {
                "type": "string",
                "description": "The product's display name."
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "The product's long-form description."
              },
              "imageUrl": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "URL of the product's main image."
              },
              "url": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "URL of the product's page on the storefront, or null if it is not known."
              },
              "metadata": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
              },
              "notes": {
                "type": "string",
                "description": "Internal notes about the product. Never shown to customers."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the product was first created in Cascade."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "When the product was last changed."
              }
            },
            "required": [
              "id",
              "slug",
              "title",
              "description",
              "imageUrl",
              "url",
              "metadata",
              "notes",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "description": "The product this line refers to."
          },
          "variant": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "Unique identifier for the variant."
                  },
                  "slug": {
                    "type": "string",
                    "description": "The variant's handle, unique within its product."
                  },
                  "title": {
                    "type": "string",
                    "description": "The variant's display name, such as its size or color."
                  },
                  "imageUrl": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "URL of the variant's image."
                  },
                  "priceCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The variant's stored price in cents, or null if it is not known."
                  },
                  "currencyCode": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The currency of `priceCents` as an ISO 4217 code, or null if it is not known."
                  },
                  "available": {
                    "anyOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Whether the variant can be bought right now, or null if no source has said. Back-in-stock alerts fire on a false to true change, so an unknown availability never triggers one."
                  },
                  "metadata": {
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
                  }
                },
                "required": [
                  "id",
                  "slug",
                  "title",
                  "imageUrl",
                  "priceCents",
                  "currencyCode",
                  "available",
                  "metadata"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The variant this line refers to, if any."
          }
        },
        "required": [
          "id",
          "productId",
          "productVariantId",
          "quantity",
          "unitPriceCents",
          "product",
          "variant"
        ],
        "additionalProperties": false
      },
      "description": "The order's line items, with their products and variants resolved."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the tags applied to the order."
    }
  },
  "required": [
    "id",
    "siteId",
    "customerId",
    "remoteId",
    "number",
    "totalCents",
    "subtotalCents",
    "shippingCents",
    "taxCents",
    "currencyCode",
    "shippedAt",
    "deliveredAt",
    "cancelledAt",
    "metadata",
    "notes",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The deleted order."
}

#Orders

GET /orders

Query Parameters

PATCH /orders/bulk-update

Query Parameters

Body Parameters

POST /orders/import

Body Parameters

GET /orders/{id}

Path Parameters

Query Parameters

PATCH /orders/{id}

Path Parameters

Body Parameters

DELETE /orders/{id}

Path Parameters

Orders

GET `/orders`

PATCH `/orders/bulk-update`

POST `/orders/import`

GET `/orders/{id}`

PATCH `/orders/{id}`

DELETE `/orders/{id}`