Order

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/shipcloud/main/json-schema/shipcloud-order-schema.json",
  "title": "Order",
  "description": "An order",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/shipcloud-openapi.yml#/components/schemas/order",
  "type": "object",
  "properties": {
    "placed_at": {
      "type": "string",
      "minLength": 1,
      "format": "date-time",
      "description": "Date that shows When the order has been placed"
    },
    "external_order_id": {
      "type": "string",
      "description": "An external identifier for this order"
    },
    "external_customer_id": {
      "type": "string",
      "description": "An external identifier for the customer who has placed the order"
    },
    "total_price": {
      "type": "number",
      "description": "The total amount of the order"
    },
    "total_vat": {
      "type": "number",
      "description": "The total VAT of the order"
    },
    "currency": {
      "type": "string",
      "minLength": 1,
      "enum": [
        "EUR",
        "USD",
        "GBP"
      ],
      "description": "Currency that the customer uses for paying the order"
    },
    "refundable_until": {
      "type": "string",
      "format": "date-time",
      "description": "Used to disable returns for the whole order after a specific time (a Return Portal Plus feature)."
    },
    "refund_deduction_amount": {
      "type": "number",
      "description": "Part of the order's return costs the customer has to pay (a Return Portal Plus feature)."
    },
    "total_weight": {
      "type": "number",
      "description": "Total weight of all items"
    },
    "weight_unit": {
      "enum": [
        "kg"
      ],
      "type": "string",
      "description": "The unit associated with the weight. Mandatory when `total_weight` is given"
    },
    "delivery_address": {
      "$ref": "#/$defs/address"
    },
    "order_line_items": {
      "type": "array",
      "description": "Array of objects containing the items that have been bought with this order",
      "items": {
        "$ref": "#/$defs/order_line_item"
      }
    }
  },
  "required": [
    "currency",
    "order_line_items",
    "total_price",
    "total_vat"
  ],
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "care_of": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional care of field"
        },
        "city": {
          "type": "string",
          "description": "Name of the city"
        },
        "country": {
          "type": "string",
          "description": "Country as uppercase ISO 3166-1 alpha-2 code"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "A persons first name"
        },
        "state": {
          "type": [
            "string",
            "null"
          ],
          "description": "The state the address is in"
        },
        "street": {
          "type": "string",
          "description": "Name of the street. Can hold the house number"
        },
        "street_no": {
          "type": [
            "string",
            "null"
          ],
          "description": "House number of the address (when a carrier requires it separately)"
        },
        "zip_code": {
          "type": "string",
          "description": "Zipcode of the address"
        },
        "phone": {
          "type": "string",
          "description": "Telephone number (mandatory when using UPS and the following terms apply: service is `one_day` or `one_day_early` or ship to country is different than ship from country)"
        },
        "email": {
          "type": "string",
          "description": "Email address for this person. Some carrier are using the email address to send notifications"
        }
      },
      "required": [
        "street",
        "city",
        "zip_code",
        "country"
      ]
    },
    "localized_attributes": {
      "title": "localized_attributes",
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "fallback": {
          "type": "string",
          "minLength": 1,
          "description": "Dynamic object to contain text in different languages. The `fallback` key has to be specified, and its value must not be empty. All other keys are optional, but if given, they should be valid lowercase `ISO-639-1` codes."
        },
        "de": {
          "type": "string"
        },
        "en": {
          "type": "string"
        }
      },
      "required": [
        "fallback"
      ]
    },
    "order_line_item": {
      "type": "object",
      "description": "",
      "title": "Order Line Item",
      "properties": {
        "sku": {
          "type": "string",
          "minLength": 1,
          "description": "Stock keeping unit"
        },
        "title": {
          "$ref": "#/$defs/localized_attributes"
        },
        "quantity": {
          "type": "number",
          "description": "Quantity of this item in the order"
        },
        "price": {
          "type": "number",
          "description": "Price the customer has to pay for a single item"
        },
        "vat": {
          "type": "number",
          "description": "VAT one has to pay for a single item"
        },
        "currency": {
          "type": "string",
          "minLength": 1,
          "description": "Currency the item has to be payed in"
        },
        "gtin": {
          "type": "string",
          "maxLength": 14,
          "description": "Global trade item number (https://www.gs1.org/standards/id-keys/gtin)"
        },
        "weight": {
          "type": "number",
          "description": "How much a single item is weighing"
        },
        "weight_unit": {
          "type": "string",
          "description": "Unit used for the weight measurement",
          "enum": [
            "kg"
          ]
        },
        "external_order_line_item_id": {
          "type": "string",
          "description": "An external identifier for this order line item"
        },
        "item_info": {
          "type": "array",
          "uniqueItems": true,
          "minItems": 0,
          "description": "Information about this variant version of the product. Used to display a (localized) label and value pair to describe an item's property, e.g. a product category.",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "$ref": "#/$defs/localized_attributes"
              },
              "value": {
                "$ref": "#/$defs/localized_attributes"
              }
            },
            "required": [
              "name",
              "value"
            ]
          }
        },
        "gross_price": {
          "type": "number",
          "description": "Gross price in Euro of an item. Used to calculate the refund amount of a return shipment (a Return Portal Plus feature)."
        },
        "returnability": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "returnable": {
              "type": "boolean",
              "description": "Indicates if an order line item can be returned (a Return Portal Plus feature)."
            },
            "returnable_until": {
              "type": "string",
              "format": "date-time",
              "description": "Used to disable returns for an order line item after a specific time."
            },
            "nonreturnable_reason": {
              "$ref": "#/$defs/localized_attributes"
            }
          }
        }
      },
      "required": [
        "sku",
        "title",
        "quantity",
        "price",
        "vat",
        "currency"
      ]
    }
  }
}