> ## Documentation Index > Fetch the complete documentation index at: https://docs.florists.digital/llms.txt > Use this file to discover all available pages before exploring further. # List orders > Required scope: `partner.orders.read`. The optional `partner.customers.pii` scope only controls PII field population; without it customer and recipient contact fields, fulfilment address, notes, and assigned florist name are returned as `null`. ## OpenAPI ````yaml /api-reference/openapi.json get /orders openapi: 3.1.0 info: title: Digital Florists Partner API version: v1 description: >- Orders, customers and products (reads plus customer creation) and outbound webhooks. Bearer authentication; per-shop base URL. servers: - url: https://{shop_domain}/api/partner/v1 description: Shop variables: shop_domain: default: your-shop.example security: - bearerAuth: [] paths: /orders: get: tags: - Orders summary: List orders description: >- Required scope: `partner.orders.read`. The optional `partner.customers.pii` scope only controls PII field population; without it customer and recipient contact fields, fulfilment address, notes, and assigned florist name are returned as `null`. operationId: partner.v1.orders.index parameters: - name: filter[status] in: query schema: type: string enum: - pending - confirmed - in_progress - out_for_delivery - fulfilled - cancelled - name: filter[payment_status] in: query schema: type: string enum: - unpaid - partially_paid - paid - refunded - partially_refunded - voided - name: filter[fulfilment_method] in: query schema: type: string enum: - delivery - collection - relay - name: filter[fulfilment_date] in: query description: >- Filter by fulfilment month (YYYY-MM) or fulfilment date (YYYY-MM-DD). schema: type: string pattern: ^\d{4}-\d{2}(-\d{2})?$ - name: filter[updated_since] in: query schema: type: string format: date-time - name: per_page in: query schema: type: integer minimum: 1 maximum: 100 description: Page size. Values above the maximum are clamped. - name: cursor in: query schema: type: string responses: '200': description: A page of orders. content: application/json: schema: $ref: '#/components/schemas/OrderList' examples: success: summary: Example response value: data: - id: 5001 reference: WEB-10001 status: confirmed payment_status: paid fulfilment_method: delivery fulfilment_date: '2026-07-02' fulfilment_at: '2026-07-02T13:00:00+01:00' fulfilment_window: between 13:00-15:00 assigned_florist: name: Sam Rivera recipient: type: contact id: 202 name: null company_name: null email: null phone: null customer: type: customer id: 101 name: null first_name: null last_name: null company_name: null email: null phone: null address: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' address: address_line_one: 10 Example Street address_line_two: null address_line_three: null town: Manchester county: null postcode: M1 1AE country: GB line_items: - product_id: 2048 variant: id: 4096 name: Large sku: HTB-001 name: Seasonal Hand-tied Bouquet quantity: 1 unit_price: 49 line_total: 49 tax_total: 8.17 note: null card_message: null discount_total: 0 total: 54.99 tax_total: 9.17 fulfilment_charge: 5.99 currency: GBP notes: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' links: next: >- https://your-shop.example/api/partner/v1/orders?cursor=eyJleGFtcGxlIjp0cnVlfQ prev: null meta: per_page: 25 has_more: true '401': $ref: '#/components/responses/AuthenticationException' description: >- Authentication failed, or the token is missing, invalid, expired, or revoked. '403': $ref: '#/components/responses/ForbiddenError' description: >- The token lacks the required scope, or API access is not enabled for this shop. '422': $ref: '#/components/responses/ValidationException' description: The request failed validation. '429': $ref: '#/components/responses/RateLimitError' description: >- Rate limit exceeded. Retry after the period given in the Retry-After header. '500': $ref: '#/components/responses/ServerError' description: An unexpected server error occurred. '503': $ref: '#/components/responses/ServiceUnavailableError' description: The partner API is temporarily disabled. Retry later. security: - bearerAuth: [] components: schemas: OrderList: type: object properties: data: type: array items: $ref: '#/components/schemas/Order' links: type: object properties: next: type: - string - 'null' prev: type: - string - 'null' required: - next - prev meta: type: object properties: per_page: type: integer minimum: 1 maximum: 100 has_more: type: boolean required: - per_page - has_more required: - data - links - meta title: OrderList example: data: - id: 5001 reference: WEB-10001 status: confirmed payment_status: paid fulfilment_method: delivery fulfilment_date: '2026-07-02' fulfilment_at: '2026-07-02T13:00:00+01:00' fulfilment_window: between 13:00-15:00 assigned_florist: name: Sam Rivera recipient: type: contact id: 202 name: null company_name: null email: null phone: null customer: type: customer id: 101 name: null first_name: null last_name: null company_name: null email: null phone: null address: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' address: address_line_one: 10 Example Street address_line_two: null address_line_three: null town: Manchester county: null postcode: M1 1AE country: GB line_items: - product_id: 2048 variant: id: 4096 name: Large sku: HTB-001 name: Seasonal Hand-tied Bouquet quantity: 1 unit_price: 49 line_total: 49 tax_total: 8.17 note: null card_message: null discount_total: 0 total: 54.99 tax_total: 9.17 fulfilment_charge: 5.99 currency: GBP notes: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' links: next: >- https://your-shop.example/api/partner/v1/orders?cursor=eyJleGFtcGxlIjp0cnVlfQ prev: null meta: per_page: 25 has_more: true Order: type: object properties: id: type: integer reference: type: - string - 'null' example: WEB-10001 status: type: string enum: - pending - confirmed - in_progress - out_for_delivery - fulfilled - cancelled example: confirmed payment_status: type: string enum: - unpaid - partially_paid - paid - refunded - partially_refunded - voided example: paid fulfilment_method: type: - string - 'null' enum: - delivery - collection - relay - null example: delivery fulfilment_date: type: - string - 'null' format: date example: '2026-07-02' fulfilment_at: type: - string - 'null' format: date-time example: '2026-07-02T13:00:00+01:00' fulfilment_window: type: - string - 'null' description: >- Human-readable fulfilment time or window in local shop time, for example "between 13:00-15:00", "before 15:00" or "13:00". Null unless the token also has partner.customers.pii, unless a non-sensitive public label applies. example: between 13:00-15:00 assigned_florist: type: - object - 'null' properties: name: type: string required: - name description: >- The assigned florist staff name (operational disclosure); null when no florist is assigned. recipient: anyOf: - $ref: '#/components/schemas/Recipient' - type: 'null' description: >- Recipient identity is present when known; contact fields inside it are null unless the token also has partner.customers.pii. customer: anyOf: - $ref: '#/components/schemas/Customer' - type: 'null' description: >- Buyer customer. Contact fields inside it are null unless the token also has partner.customers.pii. address: anyOf: - type: object properties: address_line_one: type: - string - 'null' example: 10 Example Street address_line_two: type: - string - 'null' example: null address_line_three: type: - string - 'null' example: null town: type: - string - 'null' example: Manchester county: type: - string - 'null' example: null postcode: type: - string - 'null' example: M1 1AE country: type: - string - 'null' example: GB required: - address_line_one - address_line_two - address_line_three - town - county - postcode - country - type: 'null' description: >- Delivery/fulfilment address (operational disclosure); null when the order has no address. line_items: type: array items: $ref: '#/components/schemas/LineItem' discount_total: type: number format: float description: Gross, in the shop currency. example: 0 total: type: number format: float description: Gross, in the shop currency. example: 54.99 tax_total: type: number format: float description: >- Gross VAT amount, in the shop currency. Includes fulfilment and order-level adjustments, so it can exceed the sum of line tax_total values. example: 9.17 fulfilment_charge: type: number format: float description: Gross, in the shop currency. example: 5.99 currency: type: string example: GBP notes: anyOf: - type: object properties: order: type: - string - 'null' fulfilment: type: - string - 'null' required: - order - fulfilment - type: 'null' description: Null unless the token also has partner.customers.pii. created_at: type: - string - 'null' format: date-time example: '2026-06-27T10:15:00+01:00' updated_at: type: - string - 'null' format: date-time example: '2026-06-27T10:20:00+01:00' required: - id - reference - status - payment_status - fulfilment_method - fulfilment_date - fulfilment_at - fulfilment_window - assigned_florist - recipient - customer - address - line_items - discount_total - total - tax_total - fulfilment_charge - currency - notes - created_at - updated_at title: Order example: id: 5001 reference: WEB-10001 status: confirmed payment_status: paid fulfilment_method: delivery fulfilment_date: '2026-07-02' fulfilment_at: '2026-07-02T13:00:00+01:00' fulfilment_window: between 13:00-15:00 assigned_florist: name: Sam Rivera recipient: type: contact id: 202 name: null company_name: null email: null phone: null customer: type: customer id: 101 name: null first_name: null last_name: null company_name: null email: null phone: null address: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' address: address_line_one: 10 Example Street address_line_two: null address_line_three: null town: Manchester county: null postcode: M1 1AE country: GB line_items: - product_id: 2048 variant: id: 4096 name: Large sku: HTB-001 name: Seasonal Hand-tied Bouquet quantity: 1 unit_price: 49 line_total: 49 tax_total: 8.17 note: null card_message: null discount_total: 0 total: 54.99 tax_total: 9.17 fulfilment_charge: 5.99 currency: GBP notes: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' Recipient: type: object properties: type: type: string enum: - customer - contact example: contact id: type: integer example: 202 name: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null company_name: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null email: type: - string - 'null' format: email description: Null unless the token also has partner.customers.pii. example: null phone: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null required: - type - id - name - company_name - email - phone title: Recipient Customer: type: object properties: type: type: string enum: - customer - contact example: customer id: type: integer example: 101 name: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null first_name: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null last_name: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null company_name: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null email: type: - string - 'null' description: >- One or more email addresses, semicolon-separated when multiple. Null unless the token also has partner.customers.pii. example: null phone: type: - string - 'null' description: Null unless the token also has partner.customers.pii. example: null address: anyOf: - type: object properties: address_line_one: type: - string - 'null' example: 10 Example Street address_line_two: type: - string - 'null' example: null address_line_three: type: - string - 'null' example: null town: type: - string - 'null' example: Manchester county: type: - string - 'null' example: null postcode: type: - string - 'null' example: M1 1AE country: type: - string - 'null' example: GB required: - address_line_one - address_line_two - address_line_three - town - county - postcode - country - type: 'null' description: Null unless the token also has partner.customers.pii. created_at: type: - string - 'null' format: date-time example: '2026-06-27T10:15:00+01:00' updated_at: type: - string - 'null' format: date-time example: '2026-06-27T10:20:00+01:00' required: - type - id - name - first_name - last_name - company_name - email - phone - address - created_at - updated_at title: Customer example: type: customer id: 101 name: null first_name: null last_name: null company_name: null email: null phone: null address: null created_at: '2026-06-27T10:15:00+01:00' updated_at: '2026-06-27T10:20:00+01:00' LineItem: type: object properties: product_id: type: - integer - 'null' example: 2048 variant: anyOf: - type: object properties: id: type: integer name: type: - string - 'null' sku: type: - string - 'null' required: - id - name - sku - type: 'null' description: Catalogue variant identity for stocked lines; null for custom lines. name: type: - string - 'null' description: Catalogue product, variant, or custom line item name. example: Seasonal Hand-tied Bouquet quantity: type: integer example: 1 unit_price: type: number format: float description: Gross, in the shop currency. example: 49 line_total: type: number format: float description: Gross, in the shop currency. example: 49 tax_total: type: number format: float description: Gross VAT amount, in the shop currency. example: 8.17 note: type: - string - 'null' description: >- Free-text item note. Null unless the token also has partner.customers.pii. example: null card_message: type: - string - 'null' description: >- Gift card message. Null unless the token also has partner.customers.pii. example: null required: - product_id - variant - name - quantity - unit_price - line_total - tax_total - note - card_message title: LineItem example: product_id: 2048 variant: id: 4096 name: Large sku: HTB-001 name: Seasonal Hand-tied Bouquet quantity: 1 unit_price: 49 line_total: 49 tax_total: 8.17 note: null card_message: null responses: AuthenticationException: description: Unauthenticated content: application/json: schema: type: object properties: error: type: string description: Stable machine-readable error code. message: type: string description: Human-readable error overview. required: - error - message ForbiddenError: description: >- The token lacks the required scope, or API access is not enabled for this shop. content: application/json: schema: type: object properties: error: type: string description: Stable machine-readable error code. message: type: string description: Human-readable error overview. required: - error - message ValidationException: description: The request failed validation. content: application/json: schema: type: object properties: error: type: string description: Stable machine-readable error code. message: type: string description: Human-readable validation overview. errors: type: object additionalProperties: type: array items: type: string description: Validation messages keyed by request field. required: - error - message - errors RateLimitError: description: >- Rate limit exceeded. Retry after the period given in the Retry-After header. content: application/json: schema: type: object properties: error: type: string description: Stable machine-readable error code. message: type: string description: Human-readable error overview. retry_after: type: - integer - 'null' description: Seconds to wait before retrying. required: - error - message - retry_after ServerError: description: An unexpected server error occurred. content: application/json: schema: type: object properties: error: type: string description: Stable machine-readable error code. message: type: string description: Human-readable error overview. required: - error - message ServiceUnavailableError: description: The partner API is temporarily disabled. Retry later. content: application/json: schema: type: object properties: error: type: string description: Stable machine-readable error code. message: type: string description: Human-readable error overview. required: - error - message securitySchemes: bearerAuth: type: http scheme: bearer ````