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, Users, and optionally Subscriptions. Each order has a unique ID and a human-readable order number that can be used for customer-facing references.

Endpoints

MethodEndpointDescription
GET/v0/orders/listList and filter orders
GET/v0/orders/{orderIdOrNumber}Retrieve an order by ID or number
PATCH/v0/orders/{orderIdOrNumber}/updateUpdate order details
PATCH/v0/orders/{orderIdOrNumber}/cancelCancel an order
PATCH/v0/orders/{orderIdOrNumber}/refundRefund a paid order (full or partial)

Refunds

PATCH /v0/orders/{orderIdOrNumber}/refund refunds a paid order. Omit amount for a full refund, or pass it in the order's smallest currency unit for a partial one (1999 is $19.99; 1999 in JPY is ¥1999). The currency always comes from the order — do not send one. The customer is refunded first, and the platform fee is adjusted for the refunded amount.

Two things can turn the endpoint off, and they answer differently:

StatusMeaning
403Refunds are not enabled for your workspace. Contact support to enable them.
404Either the refunds endpoint is not available at all, or that order does not exist.
400The order exists but cannot be refunded — paid through a processor that doesn't support refunds through this API, an unrefundable status, or an amount above what is still refundable. The message says which.

Branch on 403 and 404 separately: a 403 is a settings problem you can get fixed, a 404 on a known-good order id is not.

Idempotency

Always send a stable idempotencyKey when you retry. Retries carrying the same key are deduplicated. A refund sent without a key is not guaranteed to be deduplicated, so retrying one after a lost response can refund twice.

With an idempotencyKey:

Repeat ofResult
A non-exhausting partial refundReturns the original refund. No second refund, no status change, no extra notification.
A full refund, an exhausting partial, or one above the currently refundable amount400 — a fresh eligibility check now rejects it. Retry with a smaller amount, or contact support to confirm the first refund's status.

Full reference: Refund order payment.

The Order object

objectstring

Object type identifier. Always "order" for Order objects.

idstringrequired

Unique identifier (UUID) for this order.

numberstringrequired

Human-readable order number (e.g., L8VQK3N2M7KpQ9nR). Used for customer-facing references and support. The dashboard shows this with a leading #; the API never returns one. Order endpoints accept the number with or without the # — see ID formats.

statusstringrequired

Current order status. Possible values: PENDING, PAID, FAILED, UNPAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, EXPIRED

valueinteger

Total order value in the smallest currency unit (e.g., cents for USD). Defaults to 0.

taxinteger

Tax amount in the smallest currency unit. Defaults to 0.

feeinteger

Processing fee in the smallest currency unit. Defaults to 0.

currencystring | null

Three-letter ISO 4217 currency code (e.g., "USD", "EUR", "GBP").

currencyDecimalsinteger | null

Number of decimal places for the currency. Used for formatting display values.

countrystring | null

Two-letter ISO 3166-1 alpha-2 country code where the order originated.

totalItemsinteger

Total number of items in the order. Defaults to 0.

createdAtinteger

Unix timestamp in milliseconds when the order was created.

userIdstring | null

UUID of the User who placed the order.

userUser | null

Expanded User object with basic information about the customer.

user properties
objectstring

Always "user".

idstringrequired

Unique identifier (UUID) for this user.

usernamestring | null

Username of the user.

lastPaymentIdstring | null

UUID of the most recent Payment associated with this order.

lastPaymentNumberstring | null

Human-readable number of the most recent payment.

lastPaymentPayment | null

Expanded Payment object with details about the most recent payment.

lastPayment properties
objectstring

Always "payment".

idstringrequired

Unique identifier (UUID) for this payment.

typestringrequired

Payment type: one_time, subscription_initial, subscription_update, subscription_interval, subscription_extra, claim_free

numberstringrequired

Human-readable payment number.

statusstringrequired

Current payment status.

checkoutIdstring | null

UUID of the checkout element this order originated from, if it was created through one. null otherwise. Filter orders by it with the checkoutIds query parameter on list.

subscriptionIdstring | null

Identifier of the Subscription if this order is part of a recurring subscription.

subscriptionSubscription | null

Expanded Subscription object if this order is subscription-related.

subscription properties
objectstring

Always "subscription".

idstringrequired

Subscription identifier.

statusstringrequired

Subscription status: active, past_due, canceled, unpaid, incomplete, incomplete_expired, trialing, paused

Example response

{
  "status": "success",
  "data": {
    "order": {
      "object": "order",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "L8VQK3N2M7KpQ9nR",
      "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": "L8VQK3N2M7KpQ9nR",
      "lastPayment": {
        "object": "payment",
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "type": "one_time",
        "number": "L8VQK3N2M7KpQ9nR",
        "status": "PAID"
      },
      "checkoutId": "aa0e8400-e29b-41d4-a716-446655440007",
      "subscriptionId": null,
      "subscription": null
    }
  }
}

Users

Customer accounts linked to orders

Payments

Payment transactions for orders

Subscriptions

Recurring order subscriptions

Events

Webhook events for order changes

Last updated

Discount

The Discount object represents a price reduction that can be applied to purchases.

Payment

The Payment object represents a financial transaction in your Fungies store.