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

# Order

> The Order object represents a purchase transaction in your Fungies store.

An Order object represents a purchase transaction made by a customer. Orders are created when a customer initiates checkout and contain information about what was purchased, the total value, tax details, and the current status of the transaction.

Orders can contain one or more items and are linked to [Payments](/core-resources/payment), [Users](/core-resources/user), and optionally [Subscriptions](/core-resources/subscription). Each order has a unique ID and a human-readable order number that can be used for customer-facing references.

## Endpoints

| Method  | Endpoint                       | Description                       |
| ------- | ------------------------------ | --------------------------------- |
| `GET`   | `/v0/orders/list`              | List and filter orders            |
| `GET`   | `/v0/orders/{orderIdOrNumber}` | Retrieve an order by ID or number |
| `PATCH` | `/v0/orders/{orderId}/update`  | Update order details              |
| `PATCH` | `/v0/orders/{orderId}/cancel`  | Cancel an order                   |

## The Order object

<ResponseField name="object" type="string">
  Object type identifier. Always `"order"` for Order objects.
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for this order.
</ResponseField>

<ResponseField name="number" type="string" required>
  Human-readable order number (e.g., `#ABC123DEF456`). Used for customer-facing references and support.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current order status. Possible values: `PENDING`, `PAID`, `FAILED`, `UNPAID`, `CANCELLED`, `REFUNDED`, `PARTIALLY_REFUNDED`, `EXPIRED`
</ResponseField>

<ResponseField name="value" type="integer">
  Total order value in the smallest currency unit (e.g., cents for USD). Defaults to `0`.
</ResponseField>

<ResponseField name="tax" type="integer">
  Tax amount in the smallest currency unit. Defaults to `0`.
</ResponseField>

<ResponseField name="fee" type="integer">
  Processing fee in the smallest currency unit. Defaults to `0`.
</ResponseField>

<ResponseField name="currency" type="string | null">
  Three-letter ISO 4217 currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`).
</ResponseField>

<ResponseField name="currencyDecimals" type="integer | null">
  Number of decimal places for the currency. Used for formatting display values.
</ResponseField>

<ResponseField name="country" type="string | null">
  Two-letter ISO 3166-1 alpha-2 country code where the order originated.
</ResponseField>

<ResponseField name="totalItems" type="integer">
  Total number of items in the order. Defaults to `0`.
</ResponseField>

<ResponseField name="createdAt" type="integer">
  Unix timestamp in milliseconds when the order was created.
</ResponseField>

<ResponseField name="userId" type="string | null">
  UUID of the [User](/core-resources/user) who placed the order.
</ResponseField>

<ResponseField name="user" type="User | null">
  Expanded [User object](/core-resources/user) with basic information about the customer.

  <Expandable title="user properties">
    <ResponseField name="object" type="string">
      Always `"user"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this user.
    </ResponseField>

    <ResponseField name="username" type="string | null">
      Username of the user.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lastPaymentId" type="string | null">
  UUID of the most recent [Payment](/core-resources/payment) associated with this order.
</ResponseField>

<ResponseField name="lastPaymentNumber" type="string | null">
  Human-readable number of the most recent payment.
</ResponseField>

<ResponseField name="lastPayment" type="Payment | null">
  Expanded [Payment object](/core-resources/payment) with details about the most recent payment.

  <Expandable title="lastPayment properties">
    <ResponseField name="object" type="string">
      Always `"payment"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for this payment.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Payment type: `one_time`, `subscription_initial`, `subscription_update`, `subscription_interval`, `subscription_extra`, `claim_free`
    </ResponseField>

    <ResponseField name="number" type="string" required>
      Human-readable payment number.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current payment status.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="subscriptionId" type="string | null">
  Identifier of the [Subscription](/core-resources/subscription) if this order is part of a recurring subscription.
</ResponseField>

<ResponseField name="subscription" type="Subscription | null">
  Expanded [Subscription object](/core-resources/subscription) if this order is subscription-related.

  <Expandable title="subscription properties">
    <ResponseField name="object" type="string">
      Always `"subscription"`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Subscription identifier.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Subscription status: `active`, `past_due`, `canceled`, `unpaid`, `incomplete`, `incomplete_expired`, `trialing`, `paused`
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "order": {
      "object": "order",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "#ABC123DEF456",
      "status": "PAID",
      "value": 2999,
      "tax": 500,
      "fee": 87,
      "currency": "USD",
      "currencyDecimals": 2,
      "country": "US",
      "totalItems": 1,
      "createdAt": 1705590000000,
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "user": {
        "object": "user",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "johndoe"
      },
      "lastPaymentId": "660e8400-e29b-41d4-a716-446655440001",
      "lastPaymentNumber": "#PAY123DEF456",
      "lastPayment": {
        "object": "payment",
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "type": "one_time",
        "number": "#PAY123DEF456",
        "status": "PAID"
      },
      "subscriptionId": null,
      "subscription": null
    }
  }
}
```

***

## Related resources

<CardGroup cols={2}>
  <Card title="Users" icon="user" href="/core-resources/user">
    Customer accounts linked to orders
  </Card>

  <Card title="Payments" icon="credit-card" href="/core-resources/payment">
    Payment transactions for orders
  </Card>

  <Card title="Subscriptions" icon="rotate" href="/core-resources/subscription">
    Recurring order subscriptions
  </Card>

  <Card title="Events" icon="bell" href="/core-resources/event">
    Webhook events for order changes
  </Card>
</CardGroup>