# About the Order Billing API

The Order Billing API allows you to manage payments and refunds for Wix eCommerce orders.
The API centralizes all payment-related capabilities for eCommerce orders, supporting a wide range of business use cases, including charging unpaid orders with saved payment methods, capturing and voiding authorized payments, and processing refunds.

With the Order Billing API, you can:
+ [Authorize payments for orders with saved payment methods](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::authorize-charge-with-saved-payment-method*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/authorize-charge-with-saved-payment-method).
+ [Capture](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::capture-authorized-payments*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/capture-authorized-payments) or [void](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::void-authorized-payments*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/void-authorized-payments) authorized payments.
+ [Retrieve the refundability status of an order](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::get-order-refundability*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/get-order-refundability) and check the amounts available for refund.
+ [Calculate the refundable amount](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::calculate-refund*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/calculate-refund) for specific items, shipping, or additional fees, including taxes and discounts.
+ [Issue refunds](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::refund-payments*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/refund-payments) for supported payment providers, and mark refunds performed on systems other than Wix as externally refunded.

After capturing a payment or issuing a refund with the Order Billing API, you can manage the records of these payments and refunds with the [Order Transactions API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::12e752bf-af0b-4cf5-ae1e-91e68a073e3dslug::introduction*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-transactions/introduction).

## Before you begin

It’s important to note the following before starting to code:

+ At the moment, this API only supports payments from payment service providers. Paying with a gift card or by using a membership is not yet supported.
+ Charging payments with this API is limited to saved payment methods and authorized payments only.
+ Authorizing payments (delayed capture) is only available for Wix Payments.
+ Capturing or voiding authorized payments is only supported for the full authorized amount. Partial captures or voids are not currently available.
+ Most payment providers can be automatically refunded using the [Refund Payments](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::refund-payments*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/refund-payments) method. For unsupported payment providers, use the API to manually mark the payments as externally refunded. This ensures alignment between Wix and external systems.

## Use cases

+ [Authorization and capture with a saved payment method](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/sample-flows)
+ [Process the refund of an entire order](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/sample-flows)
+ [Process the partial refund of an order](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/sample-flows)
+ [Record a refund made on an external system](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::99a9bf7d-b206-488d-9d56-7e325b41b96eslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/sample-flows)

## Terminology

+ **Regular payment:** A standard payment processed via supported payment providers. This represents only monetary transactions, not gift cards or memberships.
+ **Offline payment:** A payment not processed by Wix, but still recorded by Wix.
+ **Saved payment method:** Card tokenization replaces sensitive card details with a secure, unique token to protect data during transactions and enable safer digital payments. You can specify that an item requires a saved payment method at checkout with the [Catalog Service Plugin](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::510e5aea-86ff-4f37-a49a-d826459552c6slug::introduction*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/service-plugins/catalog-service-plugin/introduction).
+ **Payment authorization:** Authorization is the process of reserving funds on a customer's payment method to ensure the payment can be completed, without immediately charging the amount.
+ **Delayed capture:** Allows businesses to charge the authorized amount at a later date. This is typically used for security deposits or order verification.
+ **Capture:** The process of transferring the reserved funds from the customer to the business.
+ **Void:** Cancels an authorized payment, and releases the reserved funds back to the customer's payment method.


+ **Refundability:** Whether an order/payment is refundable. Possible reasons why an order/payment is not refundable include pending/rejected orders, payment provider issues, and more.
+ **Shipping refund:** Refunding the amount charged for shipping fees.
+ **Additional fee refund:** Refunding the amount charged for extra fees. This may include handling fees, gift wrapping fees, or other supplementary charges.
+ **Refund statuses:**
  * `SCHEDULED` - Refund request acknowledged, and will be performed soon.
  * `STARTED` - Refund initiated on the payment provider side.
  * `PENDING` - Refund initiated on the payment provider side. This status is assigned by the payment provider.
  * `SUCCEEDED` - Refund transaction succeeded.
  * `FAILED` - Refund transaction failed.

@sdk_package_setup

# Order Billing: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as
a sample flow that could support each use case. This can be a helpful jumping
off point as you plan your app's implementation.

## Authorize and capture with a saved payment method

To authorize a payment for an order with a saved payment method, follow these steps:

1. Ensure the order has a saved payment method. To do this, pass the order ID to the [List Transactions For Single Order](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-transactions/list-transactions-for-single-order) method.
2. Search the response for a payment with `regularPaymentDetails.savedPaymentMethod` set to `true`. If no such payment exists, you will not be able to use Authorize Charge With Saved Payment Method.
3. Pass the order ID and the other required fields to [Authorize Charge With Saved Payment Method](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/authorize-charge-with-saved-payment-method). Use the `delayedCaptureSettings` field to define whether to automatically capture or void the authorized charge.
4. To capture the payment manually, pass the order ID and payment ID to [Capture Authorized Payments](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/capture-authorized-payments). Currently, capturing only the full amount is supported.
5. To void the payment, pass the order ID and payment ID to [Void Authorized Payments](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/void-authorized-payments).

## Process the refund of an entire order

To fully refund an entire order, follow these steps:

1. Pass the selected order's ID to [Get Order Refundability](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/get-order-refundability) to retrieve the refundable items and amounts.
2. Retrieve the refundable payments from the response.
3. Pass the order ID and payment IDs to [Refund Payments](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/refund-payments). Use the response from Get Order Refundability to provide the amount and items related to the refund.

## Process the partial refund of an order

Sometimes you may want to refund only a certain item. To partially refund an order, follow these steps:

1. Pass the selected order's ID to [Get Order Refundability](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/get-order-refundability) to retrieve the refundable items and amounts.
2. Retrieve the refundable payments from the response.
3. Pass the order ID and line item ID to [Calculate Refund](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/calculate-refund) to compute the refund amount for the required item, including associated taxes and discounts.
4. Pass the received amount and the line item ID to [Refund Payments](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/refund-payments) to execute the partial refund for the selected item.

## Record a refund made on an external system

In cases where the payment provider is not supported by Wix or the refund was processed outside of Wix, you can still record the refund using the Order Billing API.
To do this, follow these steps:

1. Call [Refund Payments](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/order-billing/refund-payments).
2. Pass the order ID, payment ID, and refund amount.
3. Set `externalRefund` to `true`.

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

API Reference

Velo

Picasso

GraphQL (Alpha)