About the Order Transactions API

The eCommerce Order Transactions API concentrates records and details of payments and refunds associated with eCommerce orders.

With the Order Transactions API you can:

Terminology

  • Transaction: Global term for a transfer of funds - can be either a:
    • Payment: A transfer of funds from customer to merchant/seller when making a purchase.
    • Refund A reimbursing transfer of funds back to the buyer.
Did this help?

Sample Use Case & Flow: Order Transactions

This article shares a possible use case your app could support, as well as an example flow. You're certainly not limited to this use case, but it can be a helpful jumping off point as you plan your app's implementation.

Your app can retrieve details about payments and refunds associated with an order. For example, you can check for payments that were made by credit-card, payments made by gift card, or orders that were not successfully refunded.

To retrieve info about an order's transactions:

  1. Call List Transactions For Single Order with an eCommerce order ID.
  2. You can use the returned info to check payment and refund details in the relevant provider or gateway systems, pass the details on to your accounting or invoice apps, and more.

Add payment records to imported orders

If you are importing orders from other systems, you may want to add payment records to those orders. To add a payment record to an order that is already in the eCommerce system:

  1. Once you have the order ID, pass it to the Add Payments endpoint.
  2. In the body params, pass payment details like the createdDate, amount, paymentMethod, and any other payment details.
  3. When using Add Payments you can add up to 50 payment records to a single order with 1 API call.
Did this help?

Order Transactions Object


Manage eCommerce order payments

Properties
orderIdstringformat GUID

Order ID.


paymentsArray <Payment>maxItems 100

Record of payments made to the merchant.


refundsArray <Refund>maxItems 300

Record of refunds made to the buyer.

OrderTransactions
JSON
{ "orderTransactions": { "orderId": "8d009fbe-6600-4c7a-ad23-37e9f0477947", "payments": [ { "id": "a335aebd-4688-437e-84c3-ebe947779bc1", "giftcardPaymentDetails": { "giftCardPaymentId": "ff3c2b57-2dc4-47de-a261-9ae00251a60b", "giftCardId": "", "appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27", "voided": false }, "createdDate": "2023-09-01T20:20:26.451Z", "updatedDate": "2023-09-01T20:20:26.451Z", "amount": { "amount": "25.0", "formattedAmount": "C$25.00" }, "refundDisabled": false }, { "id": "62fdfea7-896d-438d-9b88-4d7c1a4674ac", "regularPaymentDetails": { "gatewayTransactionId": "42a6c722-b27d-49fc-9a18-827115c4bd66", "paymentMethod": "Stripe", "providerTransactionId": "pi_3NmFQZINImlhPEm01iyAurzL", "offlinePayment": false, "status": "REFUNDED" }, "createdDate": "2023-09-01T20:21:26.451Z", "updatedDate": "2023-09-03T12:30:12.853Z", "amount": { "amount": "17.99", "formattedAmount": "C$17,99" }, "refundDisabled": false } ], "refunds": [ { "id": "3cfa83af-94fe-4e02-a7c7-3a969557f697", "transactions": [ { "paymentId": "62fdfea7-896d-438d-9b88-4d7c1a4674ac", "amount": { "amount": "17.99", "formattedAmount": "C$17,99" }, "refundStatus": "SUCCEEDED", "gatewayRefundId": "9656f197-74de-4d9a-bac2-85155614ef5e", "providerRefundId": "re_3NmFQZINImlhPEm011HglMxH", "externalRefund": false } ], "details": { "items": [ { "lineItemId": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ], "shippingIncluded": true }, "createdDate": "2023-09-03T12:30:12.853Z" } ] } }
Did this help?

GET

List Transactions For Single Order


Retrieves information about payments and refunds associated with a specified order.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage eCommerce - all permissions
Read eCommerce - all read permissions
Manage Stores - all permissions
Read Stores - all read permissions
Manage Orders
Read Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/ecom/v1/payments/orders/{orderId}

Path Params
orderIdstringRequired

Order ID.

Response Object
orderTransactionsOrderTransactions

Order ID and its associated transactions.

List Transactions For Single Orders
Request
cURL
curl -X GET 'https://www.wixapis.com/ecom/v1/payments/orders/8d009fbe-6600-4c7a-ad23-37e9f0477947' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "orderTransactions": { "orderId": "8d009fbe-6600-4c7a-ad23-37e9f0477947", "payments": [ { "id": "a335aebd-4688-437e-84c3-ebe947779bc1", "giftcardPaymentDetails": { "giftCardPaymentId": "ff3c2b57-2dc4-47de-a261-9ae00251a60b", "giftCardId": "", "appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27", "voided": false }, "createdDate": "2023-09-01T20:20:26.451Z", "updatedDate": "2023-09-01T20:20:26.451Z", "amount": { "amount": "25.0", "formattedAmount": "C$25.00" }, "refundDisabled": false }, { "id": "62fdfea7-896d-438d-9b88-4d7c1a4674ac", "regularPaymentDetails": { "gatewayTransactionId": "42a6c722-b27d-49fc-9a18-827115c4bd66", "paymentMethod": "Stripe", "providerTransactionId": "pi_3NmFQZINImlhPEm01iyAurzL", "offlinePayment": false, "status": "REFUNDED" }, "createdDate": "2023-09-01T20:21:26.451Z", "updatedDate": "2023-09-03T12:30:12.853Z", "amount": { "amount": "17.99", "formattedAmount": "C$17,99" }, "refundDisabled": false } ], "refunds": [ { "id": "3cfa83af-94fe-4e02-a7c7-3a969557f697", "transactions": [ { "paymentId": "62fdfea7-896d-438d-9b88-4d7c1a4674ac", "amount": { "amount": "17.99", "formattedAmount": "C$17,99" }, "refundStatus": "SUCCEEDED", "gatewayRefundId": "9656f197-74de-4d9a-bac2-85155614ef5e", "providerRefundId": "re_3NmFQZINImlhPEm011HglMxH", "externalRefund": false } ], "details": { "items": [ { "lineItemId": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ], "shippingIncluded": true }, "createdDate": "2023-09-03T12:30:12.853Z" } ] } }
Did this help?

POST

List Transactions For Multiple Orders


Retrieves information about payments and refunds associated with all specified orders.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage eCommerce - all permissions
Read eCommerce - all read permissions
Manage Stores - all permissions
Read Stores - all read permissions
Manage Orders
Read Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/ecom/v1/payments/list-by-ids

Body Params
orderIdsArray <string>RequiredminItems 1maxItems 100minLength 1maxLength 100

Order IDs for which to retrieve transactions.

Response Object
orderTransactionsArray <OrderTransactions>

List of order IDs and their associated transactions.

List Transactions For Multiple Orders

Retrieves transactions of the 2 requested order IDs

Request
cURL
curl -X POST \ 'https://www.wixapis.com/ecom/v1/payments/list-by-ids' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ --data-binary '{ "orderIds": [ "4bab5870-7943-4a9e-8d4e-96719b3e4f38", "6ae38b2e-455b-4e20-b418-01fca82edaa8" ] }'
Response
JSON
{ "orderTransactions": [ { "orderId": "4bab5870-7943-4a9e-8d4e-96719b3e4f38", "payments": [ { "id": "62fdfea7-896d-438d-9b88-4d7c1a4674ac", "regularPaymentDetails": { "gatewayTransactionId": "42a6c722-b27d-49fc-9a18-827115c4bd66", "paymentMethod": "Stripe", "providerTransactionId": "pi_3NmFQZINImlhPEm01iyAurzL", "offlinePayment": false, "status": "REFUNDED" }, "createdDate": "2023-09-03T12:29:21.284Z", "updatedDate": "2023-09-03T12:30:12.853Z", "amount": { "amount": "17.99", "formattedAmount": "17,99 €" }, "refundDisabled": false } ], "refunds": [ { "id": "3cfa83af-94fe-4e02-a7c7-3a969557f697", "transactions": [ { "paymentId": "62fdfea7-896d-438d-9b88-4d7c1a4674ac", "amount": { "amount": "17.99", "formattedAmount": "17,99 €" }, "refundStatus": "SUCCEEDED", "gatewayRefundId": "9656f197-74de-4d9a-bac2-85155614ef5e", "providerRefundId": "re_3NmFQZINImlhPEm011HglMxH", "externalRefund": false } ], "details": { "items": [ { "lineItemId": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ], "shippingIncluded": true }, "createdDate": "2023-09-03T12:30:12.853Z" } ] }, { "orderId": "6ae38b2e-455b-4e20-b418-01fca82edaa8", "payments": [ { "id": "e2f17179-db73-46ef-8d8a-06de7158e43b", "regularPaymentDetails": { "gatewayTransactionId": "6bba8866-a3af-4404-9522-61be070e4715", "paymentMethod": "Stripe", "providerTransactionId": "pi_3NiMZkLpihTBGDpG0DewjotR", "offlinePayment": false, "status": "APPROVED" }, "createdDate": "2023-08-23T19:18:46.135Z", "updatedDate": "2023-08-23T19:18:46.135Z", "amount": { "amount": "0.5", "formattedAmount": "0,50 €" }, "refundDisabled": false } ], "refunds": [] } ] }
Did this help?

POST

Add Payments


Adds up to 50 payment records to an order.

Note: This does NOT perform the actual charging - the order is only updated with records of the payments.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/ecom/v1/payments/orders/{orderId}/add-payment

Path Params
orderIdstringRequired

Order ID.

Body Params
paymentsArray <Payment>RequiredminItems 1maxItems 50

Payments to be added to order.

Response Object
orderTransactionsOrderTransactions

Order ID and its associated transactions.


paymentsIdsArray <string>

IDs of added order payments.

Add Payments
Request
cURL
curl -X POST \ 'https://www.wixapis.com/ecom/v1/payments/orders/6b51aac3-075c-4b4e-9e92-10c3730130ae/add-payment' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ --data-binary '{ "payments": [ { "amount": { "amount": "19.0" }, "refundDisabled": false, "regularPaymentDetails": { "paymentOrderId": "356e3ba8-6ee9-4f30-9ce4-cf726e4fe6f2", "gatewayTransactionId": "93eb1f1e-4c1b-4392-979c-a59d1ccf5912", "paymentMethod": "Stripe", "providerTransactionId": "pi_3Nma8hD7mauJ7ZJt0bKKZkRT", "offlinePayment": false, "status": "PENDING" } }, { "amount": { "amount": "20.0" }, "refundDisabled": true, "giftcardPaymentDetails": { "giftCardPaymentId": "e38b2b8b-f416-49b2-bbf0-869712fb9a78", "appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27" } } ] }'
Response
JSON
{ "orderTransactions": { "orderId": "6b51aac3-075c-4b4e-9e92-10c3730130ae", "payments": [ { "id": "490fa480-414e-443a-befe-13cbb2772a2f", "regularPaymentDetails": { "paymentOrderId": "356e3ba8-6ee9-4f30-9ce4-cf726e4fe6f2", "gatewayTransactionId": "93eb1f1e-4c1b-4392-979c-a59d1ccf5912", "paymentMethod": "Stripe", "providerTransactionId": "pi_3Nma8hD7mauJ7ZJt0bKKZkRT", "offlinePayment": false, "status": "PENDING" }, "createdDate": "2023-11-21T09:31:07.806Z", "updatedDate": "2023-11-21T09:31:07.806Z", "amount": { "amount": "19.0", "formattedAmount": "$19.00" }, "refundDisabled": false }, { "id": "dc67d010-529a-4cea-b78d-8283f3bd3f7b", "giftcardPaymentDetails": { "giftCardPaymentId": "e38b2b8b-f416-49b2-bbf0-869712fb9a78", "giftCardId": "", "appId": "d80111c5-a0f4-47a8-b63a-65b54d774a27", "voided": false }, "createdDate": "2023-11-21T09:31:07.806Z", "updatedDate": "2023-11-21T09:31:07.806Z", "amount": { "amount": "20.0", "formattedAmount": "$20.00" }, "refundDisabled": true } ], "refunds": [] }, "paymentsIds": [ "490fa480-414e-443a-befe-13cbb2772a2f", "dc67d010-529a-4cea-b78d-8283f3bd3f7b" ] }
Event TriggersThis method triggers the following events:
Did this help?

POST

Update Payment Status


Updates the status of an order's payment.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/ecom/v1/payments/{paymentId}/orders/{orderId}/update-payment-transaction-status

Path Params
orderIdstringRequired

Order ID.


paymentIdstringRequired

Payment ID.

Body Params
statusstring

Payment status.

Response Object
orderTransactionsOrderTransactions

Order ID and its associated transactions after update.

Request
cURL
curl -X POST \ 'https://www.wixapis.com/ecom/v1/payments/6ac204b6-d1df-44c7-ae84-aa08197380d8/orders/c7689f97-304f-425e-bbda-2451a32596c9/update-payment-transaction-status' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ --data-binary '{ "status": "APPROVED" }'
Response
JSON
{ "orderTransactions": { "orderId": "c7689f97-304f-425e-bbda-2451a32596c9", "payments": [ { "id": "6ac204b6-d1df-44c7-ae84-aa08197380d8", "regularPaymentDetails": { "paymentOrderId": null, "gatewayTransactionId": "47303d3c-5a0f-4e6f-87f4-891d89cd8203", "paymentMethod": "WixPayments", "providerTransactionId": "47303d3c-5a0f-4e6f-87f4-891d89cd8203", "offlinePayment": false, "status": "APPROVED" }, "createdDate": "2023-11-17T15:00:27.293Z", "updatedDate": "2023-11-17T15:02:10.890Z", "amount": { "amount": "99.0", "formattedAmount": "$99.00" }, "refundDisabled": false } ], "refunds": [] } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Bulk Update Payment Statuses


Updates multiple order payments with a specified status.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/ecom/v1/bulk/payments/update-payment-transaction-status

Body Params
paymentAndOrderIdsArray <PaymentAndOrderId>RequiredminItems 1maxItems 300

Order and payment IDs for which to update payment status.


returnFullEntityboolean

Whether to return the full payment entity (results.item) in the response.


statusstring

Payment status.

Response Object
resultsArray <BulkPaymentResult>

Bulk operation results.


bulkActionMetadataBulkActionMetadata

Bulk operation metadata.

Request
cURL
curl -X POST \ 'https://www.wixapis.com/ecom/v1/bulk/payments/update-payment-transaction-status' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ --data-binary '{ "paymentAndOrderIds": [ { "orderId": "69c598e5-987f-4429-9b61-76aaf47efedc", "paymentId": "770f8669-6ae7-47ed-a3fc-815ada5d86f9" }, { "orderId": "4f0cc39e-bb17-44be-bdbd-8331a5138987", "paymentId": "21cc0ff7-7ff5-4931-9ef8-1ee3d84a2215" } ], "status": "CANCELED", "returnFullEntity": false }'
Response
JSON
{ "results": [ { "itemMetadata": { "id": "770f8669-6ae7-47ed-a3fc-815ada5d86f9", "originalIndex": 0, "success": true } }, { "itemMetadata": { "id": "21cc0ff7-7ff5-4931-9ef8-1ee3d84a2215", "originalIndex": 1, "success": true } } ], "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0, "undetailedFailures": 0 } }
Event TriggersThis method triggers the following events:
Did this help?

Order Transactions Updated


Triggered when a payment or refund is added to an order, or when an existing payment is updated.

The response contains the ID of the updated order and details of its associated transactions, as well as IDs of the updated payments and refunds.

Permissions
Manage eCommerce - all permissions
Read eCommerce - all read permissions
Manage Stores - all permissions
Read Stores - all read permissions
Manage Orders
Read Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.ecom.v1.order_transactions.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


actionEventActionEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.ecom.v1.order_transactions_updated", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

OrderTransactionsUpdated
JSON
{ "id": "e883330e-6985-4b2c-b570-98260ffcf972", "entityFqdn": "wix.ecom.v1.order_transactions", "slug": "updated", "entityId": "c759ec55-52e8-45a9-a04a-71670340641d", "actionEvent": { "body": { "orderTransactions": { "orderId": "c759ec55-52e8-45a9-a04a-71670340641d", "payments": [ { "id": "1baf0a11-0c05-4bd2-b6b2-56be85c910b1", "regularPaymentDetails": { "gatewayTransactionId": "e752e841-1f6a-464c-8087-06d290ef250f", "paymentMethod": "WixPayments", "providerTransactionId": "e752e841-1f6a-464c-8087-06d290ef250f", "offlinePayment": false, "status": "REFUNDED" }, "createdDate": "2024-01-04T14:46:18.513Z", "updatedDate": "2024-01-04T14:46:38.360Z", "amount": { "amount": "84.0", "formattedAmount": "$84.00" }, "refundDisabled": false } ], "refunds": [ { "id": "961e217b-eede-4ecb-891b-8776da816074", "transactions": [ { "paymentId": "1baf0a11-0c05-4bd2-b6b2-56be85c910b1", "amount": { "amount": "84", "formattedAmount": "$84.00" }, "refundStatus": "SUCCEEDED", "gatewayRefundId": "74c5a247-f8a4-431c-ba6c-ba7234465ea9", "providerRefundId": "6728744f-6ec8-4533-b1dc-9e95ea2fd2c8", "externalRefund": false } ], "details": { "items": [], "shippingIncluded": false }, "createdDate": "2024-01-04T14:46:38.360Z" } ] }, "paymentIds": ["1baf0a11-0c05-4bd2-b6b2-56be85c910b1"], "refundIds": ["961e217b-eede-4ecb-891b-8776da816074"] } }, "eventTime": "2024-01-04T14:46:38.377953757Z", "triggeredByAnonymizeRequest": false }
Did this help?