> ## Documentation Index
> Fetch the complete documentation index at: https://help.privy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List orders

> 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`




## OpenAPI

````yaml openapi/privy-api.yaml GET /orders
openapi: 3.1.0
info:
  title: Privy API
  version: '1.0'
  description: >
    The Privy API lets you programmatically manage your contact list and read
    what you have set up in Privy.

    Create, update, unsubscribe, and remove contacts; report orders;

    and read your campaigns, flows, segments, orders, store products, coupon
    pools,

    performance reports, and account setup.
servers:
  - url: https://api.privy.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Retrieve information about the authenticated Privy account.
  - name: Contacts
    description: Manage your contact list.
  - name: Imports
    description: >-
      Read your contact import history — CSV uploads, connected-provider syncs,
      and SMS consent imports.
  - name: Campaigns
    description: >-
      Read your message campaigns — email and SMS newsletters, plus the messages
      your flows send.
  - name: Displays
    description: >-
      Read your on-site displays (popups, flyouts, banners, embedded forms,
      landing pages).
  - name: Coupons
    description: Read your coupon pools, their code inventory, and individual codes.
  - name: Reports
    description: >-
      Read performance reporting — signups, views, conversion rates, and
      attributed revenue — for your business, displays, and flows.
  - name: Flows
    description: Read your automation flows and their configuration.
  - name: Segments
    description: Read your customer segments and their membership.
  - name: Orders
    description: Report orders placed in your store and read your order history.
  - name: Products
    description: Read the product catalog and collections of your connected store.
  - name: Events
    description: Ingest custom events to trigger Flows and other automations.
paths:
  /orders:
    get:
      tags:
        - Orders
      summary: List orders
      description: >
        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`
      operationId: listOrders
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: placed_after
          in: query
          description: >-
            Only orders placed strictly after this ISO 8601 datetime (or date).
            Zone-less datetimes are interpreted as UTC; bare dates as midnight
            US Eastern time.
          schema:
            type: string
            format: date-time
          example: '2026-06-01T00:00:00Z'
        - name: placed_before
          in: query
          description: >-
            Only orders placed strictly before this ISO 8601 datetime (or date).
            Zone-less datetimes are interpreted as UTC; bare dates as midnight
            US Eastern time.
          schema:
            type: string
            format: date-time
          example: '2026-07-01T00:00:00Z'
      responses:
        '200':
          description: A paginated list of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  pagination:
                    $ref: '#/components/schemas/PaginationEnvelope'
              example:
                data:
                  - order_id: 1001
                    source: api
                    email: buyer@example.com
                    phone: '+12025550123'
                    total_amount: '95.00'
                    currency_code: USD
                    placed_at: '2026-06-01T12:00:00Z'
                    financial_status: paid
                    fulfillment_status: fulfilled
                    total_items: 2
                    created_at: '2026-06-01T12:00:05Z'
                    updated_at: '2026-06-01T12:00:05Z'
                pagination:
                  page: 1
                  per_page: 40
                  total_count: 3502
                  total_pages: 88
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
components:
  parameters:
    AccountIdParam:
      name: Privy-Account-Id
      in: header
      required: false
      description: >
        Target a subaccount instead of the main connected account.

        Pass a subaccount `id` from get_account's `subaccounts` list. Only
        direct subaccounts

        of the connected account are reachable — omit this for the main account
        itself.
      schema:
        type: string
      example: S1U2B3A4C5C6T7
    PageParam:
      name: page
      in: query
      description: Page number (starts at 1).
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 1
    PerPageParam:
      name: per_page
      in: query
      description: >-
        Number of results per page. Values outside 10–100 are clamped to the
        nearest bound.
      schema:
        type: integer
        default: 40
        minimum: 10
        maximum: 100
      example: 40
  schemas:
    Order:
      type: object
      description: |
        An order as persisted. Echoes back the fields you sent
        (column-backed fields normalized, the rest verbatim).
        Empty values are omitted from the response.
      properties:
        order_id:
          type: integer
          format: int64
          description: >-
            Your order identifier, echoed back. The only public identifier for
            the order.
          example: 1001
        source:
          type: string
          example: api
        email:
          type: string
          format: email
          example: buyer@example.com
        phone:
          type: string
          description: Normalized to E.164.
          example: '+12025550123'
        total_amount:
          type: string
          description: Order grand total, as a decimal string.
          example: '95.00'
        currency_code:
          type: string
          example: USD
        placed_at:
          type: string
          format: date-time
          example: '2026-06-01T12:00:00Z'
        financial_status:
          type: string
          description: >
            Payment status of the order, using Shopify's order financial-status
            vocabulary. Absent when

            no payment status was recorded for the order.
          example: paid
        fulfillment_status:
          type: string
          description: >
            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.
          example: fulfilled
        shipment_status:
          type: string
          description: >
            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.
          example: in_transit
        customer_id:
          type:
            - string
            - integer
          description: >
            The customer identifier reported with the order, echoed back as
            sent.
          example: ext-42
        subtotal:
          type: number
          example: 90
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        tax_lines:
          type: array
          items:
            $ref: '#/components/schemas/TaxLine'
        total_items:
          type: integer
          example: 2
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        billing_address:
          $ref: '#/components/schemas/Address'
        shipping_address:
          $ref: '#/components/schemas/Address'
        accepts_email_marketing:
          type: boolean
          description: >
            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`.
          example: true
        accepts_sms_marketing:
          type: boolean
          description: >
            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.
          example: true
        integration:
          $ref: '#/components/schemas/OrderIntegration'
        created_at:
          type: string
          format: date-time
          example: '2026-06-01T12:00:05Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-06-01T12:00:05Z'
    PaginationEnvelope:
      type: object
      properties:
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 25
        total_count:
          type: integer
          example: 142
        total_pages:
          type: integer
          example: 6
    Discount:
      type: object
      description: A discount applied to the order. Stored and echoed back verbatim.
      additionalProperties: true
      properties:
        code:
          type:
            - string
            - 'null'
          example: SAVE10
        amount:
          type:
            - number
            - 'null'
          example: 10
    TaxLine:
      type: object
      description: A tax line on the order. Stored and echoed back verbatim.
      additionalProperties: true
      properties:
        title:
          type:
            - string
            - 'null'
          example: VAT
        amount:
          type:
            - number
            - 'null'
          example: 5
    LineItem:
      type: object
      description: A product line on the order. Stored and echoed back verbatim.
      additionalProperties: true
      properties:
        product_id:
          type:
            - string
            - number
          example: prod_305
        variant_id:
          type:
            - string
            - number
          example: var_305
        sku:
          type:
            - string
            - 'null'
          example: SKU-1
        title:
          type:
            - string
            - 'null'
          example: Sample Product
        quantity:
          type:
            - integer
            - 'null'
          example: 2
        price:
          type:
            - string
            - number
            - 'null'
          description: |
            Unit price for the line, echoed back as sent.
          example: 45
    Address:
      type: object
      description: |
        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.
      additionalProperties: true
      properties:
        first_name:
          type:
            - string
            - 'null'
          example: Jane
        last_name:
          type:
            - string
            - 'null'
          example: Shopper
        name:
          type:
            - string
            - 'null'
          description: Full name; used when `first_name`/`last_name` are absent.
          example: Jane Shopper
        address1:
          type:
            - string
            - 'null'
          example: 123 Main St
        address2:
          type:
            - string
            - 'null'
          example: Apt 101
        city:
          type:
            - string
            - 'null'
          example: Boston
        state_code:
          type:
            - string
            - 'null'
          example: MA
        country_code:
          type:
            - string
            - 'null'
          example: US
        postal_code:
          type:
            - string
            - 'null'
          example: '02118'
    OrderIntegration:
      type: object
      description: >
        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).
      properties:
        store_name:
          type: string
          example: My Store
        store_url:
          type: string
          example: https://mystore.example.com
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_client
                - invalid_scope
                - unauthorized
                - insufficient_scope
                - paid_plan_required
                - api_access_required
                - not_found
                - no_connected_store
                - conflict
                - contacts_not_ready
                - validation_failed
                - rate_limited
                - store_unavailable
              example: validation_failed
            message:
              type: string
              example: One or more fields are invalid
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: email
                  message:
                    type: string
                    example: is required
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthorized
              message: Bearer token is missing or invalid
    InsufficientScope:
      description: Token lacks the required scope for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: insufficient_scope
              message: Token does not have the required scope
    ValidationFailed:
      description: One or more fields failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: validation_failed
              message: One or more fields are invalid
              details:
                - field: email
                  message: is required
    RateLimited:
      description: Rate limit exceeded. Retry after the specified time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
          example: 42
        X-RateLimit-Limit-Minute:
          description: Maximum requests allowed per minute.
          schema:
            type: integer
          example: 60
        X-RateLimit-Remaining-Minute:
          description: Requests remaining in the current minute window.
          schema:
            type: integer
          example: 0
        X-RateLimit-Reset-Minute:
          description: Unix timestamp when the minute window resets.
          schema:
            type: integer
          example: 1711929600
        X-RateLimit-Limit-Day:
          description: Maximum requests allowed per day.
          schema:
            type: integer
          example: 10000
        X-RateLimit-Remaining-Day:
          description: Requests remaining in the current day window.
          schema:
            type: integer
          example: 9500
        X-RateLimit-Reset-Day:
          description: Unix timestamp when the day window resets.
          schema:
            type: integer
          example: 1712016000
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token or OAuth access token
      description: >
        Send either an API token or an OAuth access token as

        `Authorization: Bearer <token>`. See the Authentication page for
        details.

````