---
title: "Get an order"
method: GET
path: "/orders/{order_id}"
tags: ["Orders"]
---

# Get an order

`GET /orders/{order_id}`

## Request

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

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`

## Path parameters

- `order_id` integer, required

## Headers

- `Privy-Account-Id` string

## Response `200`

The order.

- object
  - `data` Order: An order as persisted. Echoes back the fields you sent (column-backed fields normalized, the rest verbatim). Empty values are omitted from the response.
    - `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

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `404`: The requested resource does not exist or does not belong to your account.
- `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 `404`
  - 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/:order_id/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)