Manages the complete commercial and payment lifecycle of an order.
Orders bind customer information, immutable commercial terms, line items, totals, payment state, and invoice or receipt documents. Create an order, finalize it when its terms are ready, and then collect or record payment. Payment execution can require a later confirmation step; inspect the returned order and its next action instead of treating the first request as final.
Looking up an order
request = Inttegro.Orders.LookupRequest.new!(order_id: "or_...")
case Inttegro.Orders.lookup(client, request) do
{:ok, %Inttegro.Orders.Order{status: :completed} = order} ->
order
{:ok, order} ->
{:pending, order.status}
{:error, %Inttegro.Errors.APIError{} = error} ->
{:retry_or_reject, error}
endSee the Orders and payments guide for creation, idempotency, confirmation, and hosted checkout.
Summary
Functions
Cancels an existing order. execute_refund records whether a refund was requested as part of the cancellation evidence; this endpoint does not move funds or create a refund.
Marks an order as completed, transitioning it to the completed state. An order can only be completed if its associated payment has been successfully paid. Use the paid_out_of_band parameter when payment happened offline (outside the Inttegro platform) to force the payment status to paid before completing the order. This is useful for cash payments, bank transfers, or other out-of-band payment methods. Once completed, the order status becomes completed and the completed_at timestamp is set.
Confirms a pending payment using a verification token (e.g., OTP sent to customer's phone)
Creates a new order in Inttegro. This endpoint supports two flows: 1. New customer flow: Provide customer_data to create a new customer and order 2. Existing customer flow: Provide customer_id and optionally payment_method_id for known customers The order can be configured to execute payment immediately or require manual payment later.
Finalizes an order to make it ready for payment. This endpoint seals the current order state and activates the hosted checkout page that you can share with customers. Use this when you've finished building the cart and want to present it to the customer for payment. The response includes the sealed_at timestamp marking when the order was finalized. If you later need to change line items, payment method, statement descriptor, or order number, use /orders/update with an explicit finalize decision to reopen or reseal the order.
Retrieves details of an existing order by its ID. The order may or may not exist.
Retrieve a paginated list of the most recent orders for the authenticated application. Orders are sorted by initiated_at in descending order. Page numbers are zero-based, so page 0 contains the freshest activity.
Initiates payment for an existing order. Supports two payment flows: 1. Use saved payment method: Provide only order_id to charge a previously saved payment method 2. Provide new payment details: Include payment_method_data with payment information
Compatibility alias for /refunds/create. It accepts the same request and returns the same response. New integrations should use /refunds/create. Choose one URL for a logical refund and use that same URL, idempotency key, and body for every retry.
Requests a new confirmation token to be sent to the customer for payment verification
Sends the hosted invoice link for an existing order through Chime. The request body contains only order_id; delivery options are resolved from the order customer. If the customer has both a phone number and an email address, Inttegro sends both SMS and email Chimes. If only one contact method exists, Inttegro sends to that channel. The order must be finalized before Inttegro can send the hosted invoice link. This is an idempotent endpoint. Send retry keys with the Idempotency-Key header.
Sends the hosted receipt link for an existing paid order through Chime. The request body contains only order_id; receipt delivery never uses the invoice PDF path. If the customer has both a phone number and an email address, Inttegro sends both SMS and email Chimes. If only one contact method exists, Inttegro sends to that channel. The order must be paid before a receipt can be sent. This is an idempotent endpoint. Send retry keys with the Idempotency-Key header.
Updates mutable fields on an existing order and returns the same response shape as /orders/lookup. Use this endpoint to replace the order's full line item set, update the order number, receipt number, invoice settings, or statement descriptor, replace order-level custom_data, switch to a different saved payment method, tokenize a new payment method, clear the current payment method, or explicitly open, seal, or reseal the order via finalize. line_items is a full replacement field, not a sparse merge. payment_method_id, payment_method_data, and clear_payment_method are mutually exclusive. custom_data is metadata-only and does not require reopen or reseal by itself. Completed, paid, canceled, and expired orders cannot be updated. When mutating seal-sensitive fields on a sealed order, set finalize: false to reopen the order and leave it editable, or set finalize: true to apply the changes and reseal in the same request. If payment confirmation or execution has already started, Inttegro rejects edits that would change the order's economics or payment configuration.
Functions
@spec cancel(Inttegro.Client.t(), Inttegro.Orders.CancelRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Cancels an existing order. execute_refund records whether a refund was requested as part of the cancellation evidence; this endpoint does not move funds or create a refund.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.CancelRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.CancelRequest.new!(request_attributes)
case Inttegro.Orders.cancel(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec complete(Inttegro.Client.t(), Inttegro.Orders.CompleteRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Marks an order as completed, transitioning it to the completed state. An order can only be completed if its associated payment has been successfully paid. Use the paid_out_of_band parameter when payment happened offline (outside the Inttegro platform) to force the payment status to paid before completing the order. This is useful for cash payments, bank transfers, or other out-of-band payment methods. Once completed, the order status becomes completed and the completed_at timestamp is set.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.CompleteRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.CompleteRequest.new!(request_attributes)
case Inttegro.Orders.complete(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec confirm_payment( Inttegro.Client.t(), Inttegro.Orders.ConfirmPaymentRequest.t(), keyword() ) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Confirms a pending payment using a verification token (e.g., OTP sent to customer's phone)
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.ConfirmPaymentRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.ConfirmPaymentRequest.new!(request_attributes)
case Inttegro.Orders.confirm_payment(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec create(Inttegro.Client.t(), Inttegro.Orders.CreateRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Creates a new order in Inttegro. This endpoint supports two flows: 1. New customer flow: Provide customer_data to create a new customer and order 2. Existing customer flow: Provide customer_id and optionally payment_method_id for known customers The order can be configured to execute payment immediately or require manual payment later.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.CreateRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
# Build one of the concrete request variants listed by Inttegro.Orders.CreateRequest.t/0.
request = concrete_request
case Inttegro.Orders.create(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec finalize(Inttegro.Client.t(), Inttegro.Orders.FinalizeRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Finalizes an order to make it ready for payment. This endpoint seals the current order state and activates the hosted checkout page that you can share with customers. Use this when you've finished building the cart and want to present it to the customer for payment. The response includes the sealed_at timestamp marking when the order was finalized. If you later need to change line items, payment method, statement descriptor, or order number, use /orders/update with an explicit finalize decision to reopen or reseal the order.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.FinalizeRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.FinalizeRequest.new!(request_attributes)
case Inttegro.Orders.finalize(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec lookup(Inttegro.Client.t(), Inttegro.Orders.LookupRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Retrieves details of an existing order by its ID. The order may or may not exist.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.LookupRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.LookupRequest.new!(request_attributes)
case Inttegro.Orders.lookup(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec page(Inttegro.Client.t(), Inttegro.Orders.PageRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Page.t()} | {:error, Exception.t()}
Retrieve a paginated list of the most recent orders for the authenticated application. Orders are sorted by initiated_at in descending order. Page numbers are zero-based, so page 0 contains the freshest activity.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.PageRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Page.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.PageRequest.new!(request_attributes)
case Inttegro.Orders.page(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec pay(Inttegro.Client.t(), Inttegro.Orders.PayRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Initiates payment for an existing order. Supports two payment flows: 1. Use saved payment method: Provide only order_id to charge a previously saved payment method 2. Provide new payment details: Include payment_method_data with payment information
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.PayRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.PayRequest.new!(request_attributes)
case Inttegro.Orders.pay(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec refund(Inttegro.Client.t(), Inttegro.Refunds.CreateRequest.t(), keyword()) :: {:ok, Inttegro.Refunds.Refund.t()} | {:error, Exception.t()}
Compatibility alias for /refunds/create. It accepts the same request and returns the same response. New integrations should use /refunds/create. Choose one URL for a logical refund and use that same URL, idempotency key, and body for every retry.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Refunds.CreateRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Refunds.Refund.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Refunds.CreateRequest.new!(request_attributes)
case Inttegro.Orders.refund(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec request_confirmation( Inttegro.Client.t(), Inttegro.Orders.RequestConfirmationRequest.t(), keyword() ) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Requests a new confirmation token to be sent to the customer for payment verification
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.RequestConfirmationRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.RequestConfirmationRequest.new!(request_attributes)
case Inttegro.Orders.request_confirmation(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec send_invoice( Inttegro.Client.t(), Inttegro.Orders.DocumentDeliveryRequest.t(), keyword() ) :: {:ok, Inttegro.Orders.DocumentDeliveryResult.t()} | {:error, Exception.t()}
Sends the hosted invoice link for an existing order through Chime. The request body contains only order_id; delivery options are resolved from the order customer. If the customer has both a phone number and an email address, Inttegro sends both SMS and email Chimes. If only one contact method exists, Inttegro sends to that channel. The order must be finalized before Inttegro can send the hosted invoice link. This is an idempotent endpoint. Send retry keys with the Idempotency-Key header.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.DocumentDeliveryRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.DocumentDeliveryResult.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.DocumentDeliveryRequest.new!(request_attributes)
case Inttegro.Orders.send_invoice(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec send_receipt( Inttegro.Client.t(), Inttegro.Orders.DocumentDeliveryRequest.t(), keyword() ) :: {:ok, Inttegro.Orders.DocumentDeliveryResult.t()} | {:error, Exception.t()}
Sends the hosted receipt link for an existing paid order through Chime. The request body contains only order_id; receipt delivery never uses the invoice PDF path. If the customer has both a phone number and an email address, Inttegro sends both SMS and email Chimes. If only one contact method exists, Inttegro sends to that channel. The order must be paid before a receipt can be sent. This is an idempotent endpoint. Send retry keys with the Idempotency-Key header.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.DocumentDeliveryRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.DocumentDeliveryResult.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.DocumentDeliveryRequest.new!(request_attributes)
case Inttegro.Orders.send_receipt(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end@spec update(Inttegro.Client.t(), Inttegro.Orders.UpdateRequest.t(), keyword()) :: {:ok, Inttegro.Orders.Order.t()} | {:error, Exception.t()}
Updates mutable fields on an existing order and returns the same response shape as /orders/lookup. Use this endpoint to replace the order's full line item set, update the order number, receipt number, invoice settings, or statement descriptor, replace order-level custom_data, switch to a different saved payment method, tokenize a new payment method, clear the current payment method, or explicitly open, seal, or reseal the order via finalize. line_items is a full replacement field, not a sparse merge. payment_method_id, payment_method_data, and clear_payment_method are mutually exclusive. custom_data is metadata-only and does not require reopen or reseal by itself. Completed, paid, canceled, and expired orders cannot be updated. When mutating seal-sensitive fields on a sealed order, set finalize: false to reopen the order and leave it editable, or set finalize: true to apply the changes and reseal in the same request. If payment confirmation or execution has already started, Inttegro rejects edits that would change the order's economics or payment configuration.
Parameters
client— an authenticatedInttegro.Client.request— aInttegro.Orders.UpdateRequestcontaining the operation input.options— request options such as:idempotency_keyand additional:headers.
Returns
Returns {:ok, Inttegro.Orders.Order.t()} when Inttegro accepts and decodes the operation. Returns
{:error, exception} for API, transport, or decoding failures. A successful API response can
still describe an asynchronous resource that has not reached its terminal state.
Example
request = Inttegro.Orders.UpdateRequest.new!(request_attributes)
case Inttegro.Orders.update(client, request) do
{:ok, result} -> result
{:error, error} -> {:error, error}
end