Order

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/xavio-in/json-schema/xavio-in-order-schema.json",
  "title": "Order",
  "description": "One order as GET /api/v1/orders/{id} returns it. Fields marked \"customers:pii\" appear only when the key also carries the `customers:pii` scope; otherwise they are absent (ship_to) or null (buyer, delivery_agent, events[].note). The buyer's email, account id, handle, account phone and the courier label URL are never returned.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/xavio-in-openapi.json#/components/schemas/Order",
  "type": "object",
  "properties": {
    "object": {
      "type": "string",
      "enum": [
        "order"
      ]
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drawer_host_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "description": "Stored order status (pending | paid | fulfilled | cancelled | …)."
    },
    "tracking_status": {
      "type": [
        "string",
        "null"
      ],
      "description": "Fulfilment sub-state (packed | shipped | out_for_delivery | …)."
    },
    "logical_state": {
      "type": "string",
      "description": "One state to branch on, derived from status + tracking_status (pending | paid | packed | shipped | out_for_delivery | delivered | cancelled …). A confirmed COD order moves through packed / shipped / out_for_delivery while its stored status is still pending."
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "currency": {
      "type": "string"
    },
    "total_cents": {
      "type": "integer"
    },
    "fulfillment_mode": {
      "type": [
        "string",
        "null"
      ]
    },
    "promised_by": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "estimated_delivery_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "delivered_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "carrier": {
      "type": [
        "string",
        "null"
      ]
    },
    "tracking_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "tracking_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "cancel_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "cancelled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "cancelled_by": {
      "type": [
        "string",
        "null"
      ]
    },
    "payment": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "method": {
          "type": "string",
          "enum": [
            "cod",
            "prepaid",
            "wallet"
          ]
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": [
            "string",
            "null"
          ]
        },
        "amount_cents": {
          "type": [
            "integer",
            "null"
          ]
        },
        "captured_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "cod": {
      "type": [
        "object",
        "null"
      ],
      "description": "Cash-on-delivery confirmation (null for a prepaid order).",
      "properties": {
        "confirmation_status": {
          "type": [
            "string",
            "null"
          ]
        },
        "requested_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "confirmed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "confirmed_via": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "product_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "service_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "variant_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "variant_label": {
            "type": [
              "string",
              "null"
            ]
          },
          "sku": {
            "type": [
              "string",
              "null"
            ],
            "description": "Variant SKU, else the product SKU."
          },
          "qty": {
            "type": "integer"
          },
          "unit_price_cents": {
            "type": "integer"
          },
          "line_total_cents": {
            "type": "integer"
          },
          "fulfillment_status": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "money": {
      "type": "object",
      "properties": {
        "subtotal_cents": {
          "type": "integer"
        },
        "coupon_discount_cents": {
          "type": "integer"
        },
        "coupon_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "delivery_fee_cents": {
          "type": "integer"
        },
        "total_cents": {
          "type": "integer"
        }
      }
    },
    "refunds": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/OrderRefundRecord"
      }
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "carrier": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "item_ids": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "manifest_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "label_path": {
            "type": "string",
            "description": "Nafafy label path (/api/orders/<id>/shipments/<sid>/label.pdf). Downloading it needs a signed-in seller session — API keys cannot fetch labels."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Free-text log note — customers:pii only (null otherwise)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "ship_to": {
      "type": [
        "object",
        "null"
      ],
      "description": "Where the order ships. city / state / postcode / country are always present. full_name, phone, phone_masked, line1, line2 and landmark are present ONLY with the customers:pii scope. The phone is full while the order is pending or paid, masked afterwards (phone_masked: true).",
      "properties": {
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "postcode": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": [
            "string",
            "null"
          ]
        },
        "full_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "customers:pii only"
        },
        "phone": {
          "type": [
            "string",
            "null"
          ],
          "description": "customers:pii only; masked after the active stage"
        },
        "phone_masked": {
          "type": "boolean",
          "description": "customers:pii only"
        },
        "line1": {
          "type": [
            "string",
            "null"
          ],
          "description": "customers:pii only"
        },
        "line2": {
          "type": [
            "string",
            "null"
          ],
          "description": "customers:pii only"
        },
        "landmark": {
          "type": [
            "string",
            "null"
          ],
          "description": "customers:pii only"
        }
      },
      "required": [
        "city",
        "state",
        "postcode",
        "country"
      ]
    },
    "buyer": {
      "type": [
        "object",
        "null"
      ],
      "description": "customers:pii only (null otherwise).",
      "properties": {
        "display_name": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "delivery_agent": {
      "type": [
        "object",
        "null"
      ],
      "description": "customers:pii only (null otherwise).",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "vehicle": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  },
  "required": [
    "object",
    "id",
    "drawer_host_id",
    "status",
    "tracking_status",
    "logical_state",
    "created_at",
    "currency",
    "total_cents",
    "fulfillment_mode",
    "promised_by",
    "estimated_delivery_at",
    "delivered_at",
    "carrier",
    "tracking_number",
    "tracking_url",
    "cancel_reason",
    "cancelled_at",
    "cancelled_by",
    "payment",
    "cod",
    "items",
    "money",
    "refunds",
    "shipments",
    "events",
    "ship_to",
    "buyer",
    "delivery_agent"
  ],
  "$defs": {
    "OrderRefundRecord": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "amount_cents": {
          "type": "integer"
        },
        "status": {
          "type": "string",
          "description": "requested | processing | refunded | failed | needs_review | manual_payout_required (COD: cash cannot go back through a gateway; Nafafy support pays it out)."
        },
        "via": {
          "type": "string"
        },
        "full_refund": {
          "type": "boolean"
        },
        "refund_ref": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "refunded_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    }
  }
}