@spec add_services(Duffel.Client.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Duffel.Error.t()}

Adds services to an existing order, paying for them at the same time.

Examples

Duffel.Orders.add_services(client, "ord_123", %{
  add_services: [%{id: "ase_123", quantity: 1}],
  payment: %{type: "balance", currency: "GBP", amount: "15.00"}
})

@spec available_services(Duffel.Client.t(), String.t()) ::
  {:ok, [map()]} | {:error, Duffel.Error.t()}

Lists the services (e.g. extra bags, seats) available to add to an order.

@spec create(Duffel.Client.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Duffel.Error.t()}

Creates an order from a selected offer.

Build the params by hand or with Duffel.Orders.CreateParams.

A failed create is not retried automatically on the statuses Duffel calls non-retryable, and every request carries an Idempotency-Key. Duffel does not document how it treats that header, so after a failure do not assume a second attempt is free: list orders by :offer_id to see whether the booking already exists.

Options

• :idempotency_key - value for the Idempotency-Key header. A key is generated when you do not pass one (see Duffel.Client.post/4).

Examples

alias Duffel.Orders.CreateParams

params =
  CreateParams.new(
    selected_offers: ["off_123"],
    passengers: [
      CreateParams.passenger(
        id: "pas_123",
        title: "ms",
        given_name: "Amelia",
        family_name: "Earhart",
        gender: "f",
        born_on: "1987-07-24",
        email: "amelia@duffel.com",
        phone_number: "+442080160508"
      )
    ],
    payments: [CreateParams.payment(type: "balance", currency: "GBP", amount: "30.20")]
  )

Duffel.Orders.create(client, params, idempotency_key: "booking-123")

@spec get(Duffel.Client.t(), String.t()) :: {:ok, map()} | {:error, Duffel.Error.t()}

Retrieves a single order by ID.

@spec list(Duffel.Client.t(), keyword() | map()) ::
  {:ok, Duffel.Page.t()} | {:error, Duffel.Error.t()}

Lists one page of orders.

Parameters

• :booking_reference - filter by airline booking reference (PNR)
• :offer_id - filter by the offer the order was created from
• :user_id - filter by the customer user on the order
• :awaiting_payment - filter hold orders awaiting payment (boolean)
• :requires_action - orders with unactioned airline-initiated changes
• "passenger_name[]" - filter by passenger name. Pass a list to filter on several: %{"passenger_name[]" => ["Amelia", "Earhart"]}
• "owner_id[]" / "origin_id[]" / "destination_id[]" - filter by airline, origin or destination. Each takes a list, like "passenger_name[]"
• :departing_at / :arriving_at / :created_at - filter on a datetime range, e.g. created_at: %{after: "2026-07-01T00:00:00Z"}
• :sort - "payment_required_by", "total_amount", "created_at" or "next_departure", prefix with - for descending
• :limit / :after / :before - pagination (see Duffel.Page)

@spec price(Duffel.Client.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Duffel.Error.t()}

Re-prices an unpaid (hold) order with the airline and returns the updated order.

Parameters

• :intended_payment_methods - the payment methods you intend to pay with, e.g. ["card"]. Prices the order including any card fee

Examples

Duffel.Orders.price(client, "ord_123", %{intended_payment_methods: ["card"]})

@spec stream(Duffel.Client.t(), keyword() | map()) :: Enumerable.t()

Lazily streams all orders across pages.

Takes the same parameters as list/2. Raises Duffel.Error if a page request fails.

@spec update(Duffel.Client.t(), String.t(), map()) ::
  {:ok, map()} | {:error, Duffel.Error.t()}

Updates a single order. Only metadata and users are updatable.

Examples

Duffel.Orders.update(client, "ord_123", %{metadata: %{customer_id: "123"}})

Duffel.Orders.update(client, "ord_123", %{users: ["icu_123"]})