transactions

Description

This link relationship returns a collection of resources. You can easily paginate through this collection using the hypermedia links provided and the link relationships of first, prev, next, and last. Scroll down to view a representation of a single resource embedded within this collection.

Interact with this resource

To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.

Actions

GET
View a list of transactions
HEAD
Get just the header response
OPTIONS
Get a response explaining which HTTP methods are supported

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "...",
      "title": "This Collection"
    },
    "first": {
      "href": "...?offset=0",
      "title": "First Page of this Collection"
    },
    "prev": {
      "href": "...?offset=0",
      "title": "Previous Page of this Collection"
    },
    "next": {
      "href": "...?offset=0",
      "title": "Next Page of this Collection"
    },
    "last": {
      "href": "...?offset=0",
      "title": "Last Page of this Collection"
    }
  },
  "_embedded": {
    "fx:transactions": [...]
  },
  "total_items": "5",
  "returned_items": 5,
  "limit": 20,
  "offset": 0
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="...">
  <link rel="self" href="..." title="This Collection"/>
  <link rel="first" href="...?offset=0" title="First Page of this Collection"/>
  <link rel="prev" href="...?offset=0" title="Previous Page of this Collection"/>
  <link rel="next" href="...?offset=0" title="Next Page of this Collection"/>
  <link rel="last" href="...?offset=0" title="Last Page of this Collection"/>
  <resource href="..." rel="https://api.foxycart.com/rels/transaction">
  ...
  </resource>
  <total_items>5</total_items>
  <returned_items>5</returned_items>
  <limit>20</limit>
  <offset>0</offset>
</resource>

{
    "properties": {
        "total_items": "5",
        "returned_items": 5,
        "limit": 20,
        "offset": 0
    },
    "entities": [...],
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "..."
        },
        {
            "rel": [
                "first"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "prev"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "next"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "last"
            ],
            "href": "...?offset=0"
        }
    ],
    "actions": [
    ]
}

Embedded Resource: transaction

Description

A transaction is a historical record of a cart that has been purchased by a customer. To create a transaction, you post to a cart. The only aspects of a transaction which can be modified are hide_transaction and data_is_fed.

The receipt_url link relationship leads to the full HTML receipt.

If you create custom attributes for a transaction, they will automatically be included in the response as embedded resources without having to zoom in on them.

For some stores and gateways, you may see additional link relationships which allow you to modify a transaction in the following ways:

  • capture: For Auth Only transactions, you can capture them on the gateway by POSTing to the capture link relationship href with an empty body.
  • void: To reverse a recent captured transaction (usually within the same day it was completed but before batched by the gateway), POST an empty body to the void link relationship href. This will not work for auth only transactions.
  • refund: To reverse a captured transaction completed in the past, POST an empty body to the refund link relationship href. This will not work for auth only transactions.
  • transaction_logs: When modifications are made to a transaction, logs will be available for all changes to the transaction. These can be obtained via GET to the transation_logs link relationship href. You can also zoom into details by adding ?zoom=transaction_log_details

Interact with this resource

To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.

Actions

GET
View a transaction
PATCH
Update a transaction (send only the properties you want to modify)
PUT
Replace a transaction (send the entire representation)
POST
For some stores and gateways, modify this transaction via capture, void, or refund.
HEAD
Get just the header response
OPTIONS
Get a response explaining which HTTP methods are supported

Properties

Property Description Type Constraints
id The order number. Integer Read only
display_id If custom transaction IDs, prefixes, or suffixes have been configured, this value will contain the custom ID (which may be a string). Otherwise it will be identical to the id value (an integer). Integer or String Read only
is_test True if this transaction was a test transaction and not run against a live payment gateway. Boolean Read only
hide_transaction Set this to true to hide it in the FoxyCart admin. Boolean True or false, 1 or 0.
data_is_fed If the webhook for this transaction has been successfully sent, this will be true. You can also modify this to meet your needs. Boolean True or false, 1 or 0.
transaction_date The date of this transaction shown in the timezone of the store. The format used is ISO 8601 (or 'c' format string for PHP developers). Date Read only
locale_code The locale code of this transaction. This will be a copy of the store's local_code at the time of the transaction. String Read only
customer_first_name The customer's given name at the time of the transaction. String Read only
customer_last_name The customer's surname at the time of the transaction. String Read only
customer_tax_id If the customer provided a tax_id during checkout, it will be included here. String Read only
customer_email The customer's email address at the time of the transaction. Email Read only
customer_ip The customer's ip address at the time of the transaction. String Read only
ip_country The country of the customer's ip address. String Read only
total_item_price Total amount of the items in this transaction. Decimal Read only
total_tax Total amount of the taxes for this transaction. Decimal Read only
total_shipping Total amount of the shipping costs for this transaction. Decimal Read only
total_future_shipping If this transaction has any shippable subscription items which will process in the future, this will be the total amount of shipping costs for those items. Decimal Read only
total_order Total amount of this transaction including all items, taxes, shipping costs and discounts. Decimal Read only
status Used for transactions processed with a hosted payment gateway which can change the status of the transaction after it is originally posted. If the status is empty, a normal payment gateway was used and the transaction should be considered completed. String Read only. approved, authorized, declined, pending, rejected
currency_code The 3 character ISO code for the currency. String Read only
currency_symbol The currency symbol, such as $, £, €, etc. String Read only
type The type of transaction that has occurred. String Read only. updateinfo, subscription_modification, subscription_renewal or subscription_cancellation
source The source of transaction that has occurred. CIT/MIT. String Read only. cit_ecommerce, mit_uoe, mit_api, mit_recurring, mit_recurring_reattempt_automated, mit_recurring_reattempt_manual, cit_recurring_cancellation, mit_recurring_cancellation
date_created The date this resource was created. Date Read only
date_modified The date this resource was last modified. Date Read only

Example Representation

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/transactions/3820290",
            "title": "This Transaction"
        },
        "fx:attributes": {
            "href": "https://api.foxycart.com/transactions/3820290/attributes",
            "title": "Attributes for this Transaction"
        },
        "fx:store": {
            "href": "https://api.foxycart.com/stores/66",
            "title": "This Store"
        },
        "fx:receipt": {
            "href": "https://example.foxycart.com/receipt?id=6fb65c90acd74fecbe1a18834d2a1a2c",
            "title": "This Receipt",
            "type": "text/html"
        },
        "fx:customer": {
            "href": "https://api.foxycart.com/customers/115",
            "title": "This Customer"
        },
        "fx:items": {
            "href": "https://api.foxycart.com/transactions/3820290/items",
            "title": "The Items for this Transaction"
        },
        "fx:payments": {
            "href": "https://api.foxycart.com/transactions/3820290/payments",
            "title": "The Payments for this Transaction"
        },
        "fx:applied_taxes": {
            "href": "https://api.foxycart.com/transactions/3820290/applied_taxes",
            "title": "The Applied Taxes for this Transaction"
        },
        "fx:applied_gift_card_codes": {
            "href": "https://api.foxycart.com/transactions/3820290/applied_gift_card_codes",
            "title": "The Applied Gift Card Codes for this Transaction"
        }
        "fx:custom_fields": {
            "href": "https://api.foxycart.com/transactions/3820290/transaction_custom_fields",
            "title": "The Custom Fields for this Transaction"
        },
        "fx:discounts": {
            "href": "https://api.foxycart.com/transactions/3820290/discounts",
            "title": "The Discounts for this Transaction"
        },
        "fx:shipments": {
            "href": "https://api.foxycart.com/transactions/3820290/shipments",
            "title": "The Shipments for this Transaction"
        },
        "fx:billing_addresses": {
            "href": "https://api.foxycart.com/transactions/3820290/billing_addresses",
            "title": "The Billing Addresses for this Transaction"
        },
        "fx:native_integrations": {
            "href": "https://api.foxycart.com/transactions/3820290/native_integrations",
            "title": "POST here to resend transaction to the Webhooks."
        },
        "fx:process_webhook": {
            "href": "https://api.foxycart.com/transactions/3820290/process_webhook",
            "title": "POST here to resend the webhook notification for this transaction"
        },
        "fx:send_webhooks": {
            "href": "https://api.foxycart.com/transactions/3820290/send_webhooks",
            "title": "Refeed webhooks v2 for this Transaction"
        },
        "fx:send_emails": {
            "href": "https://api.foxycart.com/transactions/3820290/send_emails",
            "title": "POST here to resend emails for this transaction"
        },
        "fx:void": {
            "href": "https://api.foxycart.com/transactions/3820290/void",
            "title": "POST here to void this transaction."
        },
        "fx:refund": {
            "href": "https://api.foxycart.com/transactions/3820290/refund",
            "title": "POST here to refund this transaction."
        },
        "fx:capture": {
            "href": "https://api.foxycart.com/transactions/3820290/capture",
            "title": "POST here to capture this transaction."
        },
        "fx:transaction_logs": {
            "href": "https://api.foxycart.com/transactions/3820290/transaction_logs",
            "title": "Transaction Logs"
        }
    },
    "id": 3820290,
    "is_test": true,
    "hide_transaction": false,
    "data_is_fed": true,
    "transaction_date": "2013-06-06T17:26:07-05:00",
    "locale_code": "en_US",
    "customer_first_name": "Test",
    "customer_last_name": "User",
    "customer_tax_id": "",
    "customer_email": "testing@example.com",
    "customer_ip": "10.1.248.210",
    "ip_country": "",
    "total_item_price": 10,
    "total_tax": 1.9,
    "total_shipping": 0,
    "total_future_shipping": 0,
    "total_order": 11.9,
    "date_created": null,
    "date_modified": "2013-06-06T15:26:07-0700",
    "currency_code": "USD",
    "currency_symbol": "$"
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/transactions/3820290" rel="https://api.foxycart.com/rels/transaction">
  <link rel="self" href="https://api.foxycart.com/transactions/3820290" title="This Transaction"/>
  <link rel="https://api.foxycart.com/rels/attributes" href="https://api.foxycart.com/transactions/3820290/attributes" title="Attributes for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/66" title="This Store"/>
  <link rel="https://api.foxycart.com/rels/receipt" href="https://example.foxycart.com/receipt?id=6fb65c90acd74fecbe1a18834d2a1a2c" title="This Receipt" type="text/html"/>
  <link rel="https://api.foxycart.com/rels/customer" href="https://api.foxycart.com/customers/115" title="This Customer"/>
  <link rel="https://api.foxycart.com/rels/items" href="https://api.foxycart.com/transactions/3820290/items" title="The Items for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/payments" href="https://api.foxycart.com/transactions/3820290/payments" title="The Payments for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/applied_taxes" href="https://api.foxycart.com/transactions/3820290/applied_taxes" title="The Applied Taxes for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/applied_gift_card_codes" href="https://api.foxycart.com/transactions/3820290/applied_gift_card_codes" title="The Applied Gift Card Codes for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/custom_fields" href="https://api.foxycart.com/transactions/3820290/transaction_custom_fields" title="The Custom Fields for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/discounts" href="https://api.foxycart.com/transactions/3820290/discounts" title="The Discounts for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/shipments" href="https://api.foxycart.com/transactions/3820290/shipments" title="The Shipments for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/billing_addresses" href="https://api.foxycart.com/transactions/3820290/billing_addresses" title="The Billing Addresses for this Transaction"/>
  <link rel="https://api.foxycart.com/rels/process_webhook" href="https://api.foxycart.com/transactions/3820290/process_webhook" title="POST here to resend the webhook notification for this transaction"/>
  <link rel="https://api.foxycart.com/rels/send_webhooks" href="https://api.foxycart.com/transactions/3820290/send_webhooks" title="POST here to resend the webhook notification for this transaction"/>
  <link rel="https://api.foxycart.com/rels/send_emails" href="https://api.foxycart.com/transactions/3820290/send_emails" title="POST here to resend emails for this transaction"/>
  <link rel="https://api.foxycart.com/rels/void" href="https://api.foxycart.com/transactions/3820290/void" title="POST here to void this transaction."/>
  <link rel="https://api.foxycart.com/rels/refund" href="https://api.foxycart.com/transactions/3820290/refund" title="POST here to refund this transaction."/>
  <link rel="https://api.foxycart.com/rels/capture" href="https://api.foxycart.com/transactions/3820290/capture" title="POST here to capture this transaction."/>
  <link rel="https://api.foxycart.com/rels/transaction_logs" href="https://api.foxycart.com/transactions/3820290/transaction_logs" title="Transaction Logs"/>
  <id>3820290</id>
  <is_test>true</is_test>
  <hide_transaction>false</hide_transaction>
  <data_is_fed>true</data_is_fed>
  <transaction_date>2013-06-06T17:26:07-05:00</transaction_date>
  <locale_code>en_US</locale_code>
  <customer_first_name>Test</customer_first_name>
  <customer_last_name>User</customer_last_name>
  <customer_tax_id></customer_tax_id>
  <customer_email>testing@example.com</customer_email>
  <customer_ip>10.1.248.210</customer_ip>
  <ip_country></ip_country>
  <total_item_price>10</total_item_price>
  <total_tax>1.9</total_tax>
  <total_shipping>0</total_shipping>
  <total_future_shipping>0</total_future_shipping>
  <total_order>11.9</total_order>
  <date_created></date_created>
  <date_modified>2013-06-06T15:26:07-0700</date_modified>
</resource>

{
    "class": [
        "transaction"
    ],
    "properties": {
        "id": 3820290,
        "is_test": true,
        "hide_transaction": false,
        "data_is_fed": true,
        "transaction_date": "2013-06-06T17:26:07-05:00",
        "locale_code": "en_US",
        "customer_first_name": "Test",
        "customer_last_name": "User",
        "customer_tax_id": "",
        "customer_email": "testing@example.com",
        "customer_ip": "10.1.248.210",
        "ip_country": "",
        "total_item_price": 10,
        "total_tax": 1.9,
        "total_shipping": 0,
        "total_future_shipping": 0,
        "total_order": 11.9,
        "date_created": null,
        "date_modified": "2013-06-06T15:26:07-0700"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/transactions/3820290"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/attributes"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/attributes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api.foxycart.com/stores/66"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/receipt"
            ],
            "href": "https://example.foxycart.com/receipt?id=6fb65c90acd74fecbe1a18834d2a1a2c"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/customer"
            ],
            "href": "https://api.foxycart.com/customers/115"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/items"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/items"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/payments"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/payments"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/applied_taxes"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/applied_taxes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/applied_gift_card_codes"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/applied_gift_card_codes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/custom_fields"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/transaction_custom_fields"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/discounts"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/discounts"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/shipments"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/shipments"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/billing_addresses"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/billing_addresses"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/process_webhook"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/process_webhook"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/send_webhooks"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/send_webhooks"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/send_emails"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/send_emails"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/void"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/void"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/refund"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/refund"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/capture"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/capture"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/transaction_logs"
            ],
            "href": "https://api.foxycart.com/transactions/3820290/transaction_logs"
        }
    ]
}

Conditional Link Relationships

If the transaction creates a new subscription or subscriptions (ie. the very first transaction of a subscription), it will include a fx:subscriptions (plural) link relationship containing a link to all the subscriptions that have been created. If the transaction is from an existing subscription, it will include fx:subscription (singular) and a fx:sub_token_url link relationship if the transaction. Note that in either case these link rels will only be returned if you `zoom` on `subscriptions`.

Only select gateways and stores currently support transactions modifications. For those stores, the void, refund, and transaction_logs link relationships will be available. If the transaction was completed as an authorize only, the capture link relationship will be available for these stores as well.

Zoomable Resources

The following related resources can be embedded within this resource by including a ?zoom=<child_resource> parameter. You can also filter by child resources by ?child_resource:property=<property_value>

attributes
customer
payments
items
applied_taxes
applied_gift_card_codes
custom_fields
discounts
shipments
billing_addresses
transaction_logs
transaction_journal_entries