The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

Transaction

Requires ANY of the following access scopes: orders, marketplace_orders.

Transactions are created for every order that results in an exchange of money.

There are five types of transactions:

  • Authorization: An amount reserved against the cardholder's funding source. Money does not change hands until the authorization is captured.
  • Sale: An authorization and capture performed together in a single step.
  • Capture: A transfer of the money that was reserved during the authorization stage.
  • Void: A cancellation of a pending authorization or capture.
  • Refund: A partial or full return of captured funds to the cardholder. A refund can happen only after a capture is processed.

Refund transactions must be created by using the Refund resource.

Note

An order can have more than one authorization transaction associated with it. This might happen when an order is edited or when a post-purchase upsell is added to the order. To be notified when an order is edited subscribe to the OrderEdit webhook.

If your app captures payments, you should make a GET request to the /admin/api/{version}/orders/{order_id}/transactions.json endpoint to retrieve the authorization transactions associated with an order. Then, to complete the full order payment capture, you should use the authorization or parent_id properties in separate capture POST requests to the same endpoint for each authorization transaction.

Note

An order can have no more than 100 transactions associated with it.

Was this section helpful?
Anchor to section titled 'The Transaction resource'

The Transaction resource

Properties
amount
->amountSet
The amount of money included in the transaction. If you don't provide a value for `amount`, then it defaults to the total cost of the order (even if a previous transaction has been made towards it).
amount_rounding
read-only
->amountSet
The rounding adjustment for cash payments, to be applied on the amount to get a rounded amount.
authorization
->authorizationCode
The authorization code associated with the transaction.
authorization_expires_at
->authorizationExpiresAt
The date and time (ISO 8601 format) when the Shopify Payments authorization expires.
created_at
read-only
The date and time (ISO 8601 format) when the transaction was created.
currency
->amountSet

The three-letter code (ISO 4217 format) for the currency used for the payment.

device_id
read-only
The ID for the device.
error_code
read-only
->errorCode
A standardized error code, independent of the payment provider. Valid values:
extended_authorization_attributes
The attributes associated with a Shopify Payments extended authorization period. It has the following attributes:
gateway
->gateway
The name of the gateway the transaction was issued through. A list of gateways can be found on Shopify's payment gateways page.
id
read-only
->id
The ID for the transaction.
kind
->kind
The transaction's type. Valid values:
Was this section helpful?
{}The Transaction resource
{
  "amount": "10.00",
  "amount_rounding": "0.02",
  "authorization": "ch_1AtJu6CktlpKSclI4zjeQb2t",
  "authorization_expires_at": "2021-03-13T16:09:54-04:00",
  "created_at": "2012-03-13T16:09:54-04:00",
  "currency": "USD",
  "device_id": 1,
  "error_code": "invalid_cvc",
  "extended_authorization_attributes": {
    "standard_authorization_expires_at": "2020-10-08T00:00:00-04:00",
    "extended_authorization_expires_at": "2020-10-30T00:00:00-04:00"
  },
  "gateway": "shopify_payments",
  "id": 999225661,
  "kind": "capture",
  "location_id": {
    "id": 49202758
  },
  "message": "Marked the Stripe payment as received",
  "order_id": 450789469,
  "payment_details": {
    "credit_card_bin": "123456",
    "avs_result_code": "Y",
    "cvv_result_code": "M",
    "credit_card_number": "•••• •••• •••• 4242",
    "credit_card_company": "Visa",
    "credit_card_name": "John Smith",
    "credit_card_wallet": "shopify_pay",
    "credit_card_expiration_month": 10,
    "credit_card_expiration_year": 2028,
    "buyer_action_info": {
      "multibanco": {
        "Entity": "12345",
        "Reference": "999999999"
      }
    },
    "payment_method_name": "multibanco"
  },
  "parent_id": 584698724408,
  "payments_refund_attributes": {
    "status": "success",
    "acquirer_reference_number": "123456789012345678901234"
  },
  "processed_at": "2018-01-10T11:00:00-05:00",
  "receipt": {},
  "source_name": "web",
  "status": "success",
  "total_unsettled_set": {
    "presentment_money": {
      "amount": "171.8",
      "currency": "USD"
    },
    "shop_money": {
      "amount": "171.8",
      "currency": "USD"
    }
  },
  "test": true,
  "user_id": 106045196,
  "currency_exchange_adjustment": {
    "id": 1,
    "adjustment": "-0.01",
    "original_amount": "-53.62",
    "final_amount": "-53.63",
    "currency": "CAD"
  },
  "manual_payment_gateway": false
}
Anchor to section titled 'POST request, Creates a transaction for an order'

post
Creates a transaction for an order

orderCapture

Creates a transaction for an order.

Anchor to section titled 'Parameters of Creates a transaction for an order'

Parameters

api_version
string
required
order_id
string
required
source
An optional origin of the transaction. Set to external to import a cash transaction for the associated order.
Was this section helpful?
Anchor to section titled 'Examples of Creates a transaction for an order'

Examples

Path parameters
orderid=450789469
string
required
Request body
transaction
Transaction resource
Was this section helpful?
post
/admin/api/2024-10/orders/450789469/transactions.json
Copy
curl -d '{"transaction":{"currency":"USD","amount":"10.00","kind":"capture","parent_id":389404469}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/orders/450789469/transactions.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "transaction": {
    "id": 1068278482,
    "order_id": 450789469,
    "kind": "capture",
    "gateway": "bogus",
    "status": "success",
    "message": "Bogus Gateway: Forced success",
    "created_at": "2024-09-24T15:32:35-04:00",
    "test": true,
    "authorization": null,
    "location_id": null,
    "user_id": null,
    "parent_id": 389404469,
    "processed_at": "2024-09-24T15:32:35-04:00",
    "device_id": null,
    "error_code": null,
    "source_name": "755357713",
    "payment_details": {
      "credit_card_bin": null,
      "avs_result_code": null,
      "cvv_result_code": null,
      "credit_card_number": "•••• •••• •••• 4242",
      "credit_card_company": "Visa",
      "buyer_action_info": null,
      "credit_card_name": null,
      "credit_card_wallet": null,
      "credit_card_expiration_month": null,
      "credit_card_expiration_year": null,
      "payment_method_name": "visa"
    },
    "receipt": {},
    "currency_exchange_adjustment": null,
    "amount": "10.00",
    "currency": "USD",
    "payment_id": "c901414060.1",
    "total_unsettled_set": {
      "presentment_money": {
        "amount": "588.94",
        "currency": "USD"
      },
      "shop_money": {
        "amount": "588.94",
        "currency": "USD"
      }
    },
    "manual_payment_gateway": false,
    "amount_rounding": null,
    "admin_graphql_api_id": "gid://shopify/OrderTransaction/1068278482"
  }
}
Anchor to section titled 'GET request, Retrieves a list of transactions'

get
Retrieves a list of transactions

order

Retrieves a list of transactions.

Transactions attached to multi-currency orders are in the presentment currency by default. To retrieve transactions in the shop currency, include the URL parameter in_shop_currency=true.

Anchor to section titled 'Parameters of Retrieves a list of transactions'

Parameters

api_version
string
required
order_id
string
required
fields
Show only certain fields, specifed by a comma-separated list of fields names.
in_shop_currency
default false
Show amounts in the shop currency.
since_id
Retrieve only transactions after the specified ID.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of transactions'

Examples

Path parameters
orderid=450789469
string
required
Was this section helpful?
get
/admin/api/2024-10/orders/450789469/transactions.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/orders/450789469/transactions.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "transactions": [
    {
      "id": 179259969,
      "order_id": 450789469,
      "kind": "refund",
      "gateway": "bogus",
      "status": "success",
      "message": null,
      "created_at": "2005-08-05T12:59:12-04:00",
      "test": false,
      "authorization": "authorization-key",
      "location_id": null,
      "user_id": null,
      "parent_id": 801038806,
      "processed_at": "2005-08-05T12:59:12-04:00",
      "device_id": null,
      "error_code": null,
      "source_name": "web",
      "receipt": {},
      "currency_exchange_adjustment": null,
      "amount": "209.00",
      "currency": "USD",
      "payment_id": "#1001.3",
      "total_unsettled_set": {
        "presentment_money": {
          "amount": "348.0",
          "currency": "USD"
        },
        "shop_money": {
          "amount": "348.0",
          "currency": "USD"
        }
      },
      "manual_payment_gateway": false,
      "amount_rounding": null,
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
    },
    {
      "id": 389404469,
      "order_id": 450789469,
      "kind": "authorization",
      "gateway": "bogus",
      "status": "success",
      "message": null,
      "created_at": "2005-08-01T11:57:11-04:00",
      "test": false,
      "authorization": "authorization-key",
      "location_id": null,
      "user_id": null,
      "parent_id": null,
      "processed_at": "2005-08-01T11:57:11-04:00",
      "device_id": null,
      "error_code": null,
      "source_name": "web",
      "payment_details": {
        "credit_card_bin": null,
        "avs_result_code": null,
        "cvv_result_code": null,
        "credit_card_number": "•••• •••• •••• 4242",
        "credit_card_company": "Visa",
        "buyer_action_info": null,
        "credit_card_name": null,
        "credit_card_wallet": null,
        "credit_card_expiration_month": null,
        "credit_card_expiration_year": null,
        "payment_method_name": "visa"
      },
      "receipt": {
        "testcase": true,
        "authorization": "123456"
      },
      "currency_exchange_adjustment": null,
      "amount": "598.94",
      "currency": "USD",
      "payment_id": "#1001.1",
      "total_unsettled_set": {
        "presentment_money": {
          "amount": "348.0",
          "currency": "USD"
        },
        "shop_money": {
          "amount": "348.0",
          "currency": "USD"
        }
      },
      "manual_payment_gateway": false,
      "amount_rounding": null,
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/389404469"
    },
    {
      "id": 801038806,
      "order_id": 450789469,
      "kind": "capture",
      "gateway": "bogus",
      "status": "success",
      "message": null,
      "created_at": "2005-08-05T10:22:51-04:00",
      "test": false,
      "authorization": "authorization-key",
      "location_id": null,
      "user_id": null,
      "parent_id": 389404469,
      "processed_at": "2005-08-05T10:22:51-04:00",
      "device_id": null,
      "error_code": null,
      "source_name": "web",
      "receipt": {},
      "currency_exchange_adjustment": null,
      "amount": "250.94",
      "currency": "USD",
      "payment_id": "#1001.2",
      "total_unsettled_set": {
        "presentment_money": {
          "amount": "348.0",
          "currency": "USD"
        },
        "shop_money": {
          "amount": "348.0",
          "currency": "USD"
        }
      },
      "manual_payment_gateway": false,
      "amount_rounding": null,
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/801038806"
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a specific transaction'

get
Retrieves a specific transaction

node

Retrieves a specific transaction.

Transactions attached to multi-currency orders are in the presentment currency by default. To retrieve transactions in the shop currency, include the URL parameter in_shop_currency=true.

extended_authorization_attributes are available on this endpoint only to stores on the Shopify Plus plan that use Shopify Payments. To learn more about extended authorization periods, refer to Payment authorization.

Anchor to section titled 'Parameters of Retrieves a specific transaction'

Parameters

api_version
string
required
order_id
string
required
transaction_id
string
required
fields
Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency
default false
Show amounts in the shop currency.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a specific transaction'

Examples

Was this section helpful?
get
/admin/api/2024-10/orders/450789469/transactions/389404469.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/orders/450789469/transactions/389404469.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "transaction": {
    "id": 389404469,
    "order_id": 450789469,
    "kind": "authorization",
    "gateway": "bogus",
    "status": "success",
    "message": null,
    "created_at": "2005-08-01T11:57:11-04:00",
    "test": false,
    "authorization": "authorization-key",
    "location_id": null,
    "user_id": null,
    "parent_id": null,
    "processed_at": "2005-08-01T11:57:11-04:00",
    "device_id": null,
    "error_code": null,
    "source_name": "web",
    "payment_details": {
      "credit_card_bin": null,
      "avs_result_code": null,
      "cvv_result_code": null,
      "credit_card_number": "•••• •••• •••• 4242",
      "credit_card_company": "Visa",
      "buyer_action_info": null,
      "credit_card_name": null,
      "credit_card_wallet": null,
      "credit_card_expiration_month": null,
      "credit_card_expiration_year": null,
      "payment_method_name": "visa"
    },
    "receipt": {
      "testcase": true,
      "authorization": "123456"
    },
    "currency_exchange_adjustment": null,
    "amount": "598.94",
    "currency": "USD",
    "authorization_expires_at": null,
    "extended_authorization_attributes": {},
    "payment_id": "#1001.1",
    "total_unsettled_set": {
      "presentment_money": {
        "amount": "348.0",
        "currency": "USD"
      },
      "shop_money": {
        "amount": "348.0",
        "currency": "USD"
      }
    },
    "manual_payment_gateway": false,
    "amount_rounding": null,
    "admin_graphql_api_id": "gid://shopify/OrderTransaction/389404469"
  }
}
Anchor to section titled 'GET request, Retrieves a count of an order's transactions'

get
Retrieves a count of an order's transactions

order
Retrieves a count of an order's transactions.
Anchor to section titled 'Parameters of Retrieves a count of an order's transactions'

Parameters

api_version
string
required
order_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a count of an order's transactions'

Examples

Path parameters
orderid=450789469
string
required
Was this section helpful?
get
/admin/api/2024-10/orders/450789469/transactions/count.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/orders/450789469/transactions/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "count": 3
}