> ## 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.

# Get an order

> Retrieve a single order by its order id — the identifier assigned by the order's source
(your store platform, or the `order_id` you sent to `POST /v1/orders/placed`).

Order ids are unique per source. In the rare case two sources share an id, the most recently created order is returned.

A `/v1/orders` row already carries the whole order, so this is for an id
that came from somewhere else rather than a follow-up read.

**Required scope:** `orders_read`




## OpenAPI

````yaml openapi/privy-api.yaml GET /orders/{order_id}
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/{order_id}:
    get:
      tags:
        - Orders
      summary: Get an order
      description: >
        Retrieve a single order by its order id — the identifier assigned by the
        order's source

        (your store platform, or the `order_id` you sent to `POST
        /v1/orders/placed`).


        Order ids are unique per source. In the rare case two sources share an
        id, the most recently created order is returned.


        A `/v1/orders` row already carries the whole order, so this is for an id

        that came from somewhere else rather than a follow-up read.


        **Required scope:** `orders_read`
      operationId: getOrder
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
        - name: order_id
          in: path
          required: true
          description: >-
            The order's source-assigned id (returned as `order_id` in order
            responses).
          schema:
            type: integer
            format: int64
          example: 1001
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
              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
                  subtotal: 90
                  total_items: 2
                  line_items:
                    - sku: SKU-1
                      quantity: 2
                      price: 45
                  created_at: '2026-06-01T12:00:05Z'
                  updated_at: '2026-06-01T12:00:05Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
        '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
  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'
    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
    NotFound:
      description: >-
        The requested resource does not exist or does not belong to your
        account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: not_found
              message: Not found
    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.

````