transaction : Foxy hAPI

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