---
title: "List orders"
method: GET
path: "/orders"
tags: ["Orders"]
---

# List orders

`GET /orders`

## Request

- Base URL: `https://api.privy.com/v1`
- URL: `https://api.privy.com/v1/orders`
- Auth: HTTP bearer

Retrieve a paginated list of your orders across every source (Shopify,
BigCommerce, Weebly, Wix, and orders reported via this API), most recently created first.

Orders imported before Privy began denormalizing order timestamps may be excluded when a date filter is applied.

Rows carry the full order shape, so no per-order follow-up is needed, and
the only filters are the placed-date ones — none by contact, email, or
status.

**Required scope:** `orders_read`

## Query parameters

- `page` integer
- `per_page` integer
- `placed_after` string, date-time
- `placed_before` string, date-time

## Headers

- `Privy-Account-Id` string

## Response `200`

A paginated list of orders.

- object
  - `data` Order[]
    - `order_id` integer: Your order identifier, echoed back. The only public identifier for the order.
    - `source` string
    - `email` string, email
    - `phone` string: Normalized to E.164.
    - `total_amount` string: Order grand total, as a decimal string.
    - `currency_code` string
    - `placed_at` string, date-time
    - `financial_status` string: Payment status of the order, using Shopify's order financial-status vocabulary. Absent when no payment status was recorded for the order.
    - `fulfillment_status` string: The order's overall fulfillment state — where the order sits in the store's fulfillment process. Delivery-based flow triggers key off `shipment_status`, not this field.
    - `shipment_status` string: Carrier delivery status of the shipment — where the parcel is. Privy acts on this field: when it becomes `delivered`, the contact's "Order Received" flows start.
    - `customer_id` union: The customer identifier reported with the order, echoed back as sent.
      - string
      - integer
    - `subtotal` number
    - `discounts` Discount[]
      - `code` string, nullable
      - `amount` number, nullable
    - `tax_lines` TaxLine[]
      - `title` string, nullable
      - `amount` number, nullable
    - `total_items` integer
    - `line_items` LineItem[]
      - `product_id` union
        - string
        - number
      - `variant_id` union
        - string
        - number
      - `sku` string, nullable
      - `title` string, nullable
      - `quantity` integer, nullable
      - `price` union: Unit price for the line, echoed back as sent.
        - string
        - number
    - `billing_address` Address: A billing or shipping address. Stored and echoed back verbatim. When a new contact is created, its name is taken from the address — shipping first, billing as fallback — using `first_name`/`last_name`, or a single `name` field split on whitespace.
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `name` string, nullable: Full name; used when `first_name`/`last_name` are absent.
      - `address1` string, nullable
      - `address2` string, nullable
      - `city` string, nullable
      - `state_code` string, nullable
      - `country_code` string, nullable
      - `postal_code` string, nullable
    - `shipping_address` Address: A billing or shipping address. Stored and echoed back verbatim. When a new contact is created, its name is taken from the address — shipping first, billing as fallback — using `first_name`/`last_name`, or a single `name` field split on whitespace.
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `name` string, nullable: Full name; used when `first_name`/`last_name` are absent.
      - `address1` string, nullable
      - `address2` string, nullable
      - `city` string, nullable
      - `state_code` string, nullable
      - `country_code` string, nullable
      - `postal_code` string, nullable
    - `accepts_email_marketing` boolean: The email marketing opt-in reported with the order, echoed back as sent. It records what the order said, not the contact's consent now — read that from the contact's `email_consent`.
    - `accepts_sms_marketing` boolean: The SMS marketing opt-in reported with the order, echoed back as sent. As with `accepts_email_marketing`, the contact's current consent lives on the contact (`sms_consent`), not here.
    - `integration` OrderIntegration: The Custom Integration the order is tied to. Present only when the order was attributed to an integration (via the `X-Privy-Integration-Token` header or auto-tie).
      - `store_name` string
      - `store_url` string
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `pagination` PaginationEnvelope
    - `page` integer
    - `per_page` integer
    - `total_count` integer
    - `total_pages` integer

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `422`: One or more fields failed validation.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `cf0885e90d5a`: 8 warning
  - added the new `forbidden` enum value to the `error/code` response property for the response status `401`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `403`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `422`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `429`
  - …4 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/orders/get.md)

---

[API](https://skmtc.dev/privy/apis/privy-api.md) - [All operations](https://skmtc.dev/privy/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy/apis/privy-api/revisions/bc29b48dcdd2?raw)