cart : Foxy hAPI

carts

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 carts
POST: Create a new cart
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:carts": [...]
  },
  "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/cart">
  ...
  </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: cart

Description

A cart is an uncompleted transaction. When a customer prepares to checkout, they store the items they want to purchase in a cart first. Carts can also be converted to completed transactions which charges the customer. To do so, ensure the customer involved has a saved default_payment_method which includes a working payment card. Modify the cart with a PATCH or a PUT so the customer_uri matches the customer you want to charge. You can also just pass in the customer_id if you don't have the full uri. Once that is done, submit an HTTP POST to the cart resource to complete the transaction.

To create a link to this cart which includes the session information you need for a browser, POST to the create_session link relationship.

Interact with this resource

Actions

GET: View a cart
PATCH: Update a cart (send only the properties you want to modify)
PUT: Replace a cart (send the entire representation)
POST: Charge a customer, create a Transaction resource, and delete this cart resource
DELETE: Delete a cart
HEAD: Get just the header response
OPTIONS: Get a response explaining which HTTP methods are supported

Properties

Property	Description	Type	Constraints
customer_uri	The full API URI of the customer this cart is associated with. You can not POST a cart into a transaction (ie. charge a customer's saved payment method) unless this value is set to a valid customer with an active default payment method. Guest (ie. `is_anonymous=1` customer resources can be used, but be aware that guest customer payment methods are purged regularly and according to various internal criteria. As such, so you should not rely on a guest customer's saved credit card being usable indefinitely. In general, you shouldn't rely on a saved payment method persisting more than 60 days, though this value is subject to change. (And, of course, there's no guarantee for any saved payment method that it will work in the future, so always be sure to handle payment errors on your end.) Note that when this value is included, the customer's `shipping_` and `billing_` values will populate and override any existing values on the `cart` resource (unless the address values are PUT or PATCHed in the same request, in which case the explicitly set values will be used). Note that if you are using the `customer_uri` value, you'll likely either want to explicitly set the `use_customer_shipping_address` value.	URL	Obtained from the self link relation of a customer.
customer_email	This value will be populated when `customer_uri` is set, but can be set separately (for instance, if the customer is unknown or new. This is not used for pre-population on the checkout, but can be helpful in certain situations (such as cart abandonment tracking). Note that setting `customer_uri` will overwrite this value, and you will receive an error if you set both `customer_email` and `customer_uri` with a mismatched email address.	Email	Optional. 100 characters or less.
payment_method_uri	The full API URI of the `fx:payments` resource, from a previous transaction. This can be used in addition to the `customer_uri`, to specify a specific payment method used in the past. Without this value, the customer's default saved payment method will be used instead. This can be helpful in certain situations, such as when a customer may use multiple different payment methods, but you need to use the API to charge a specific payment method. For instance, if a customer makes 3 transactions with 3 different credit cards, and you need to add a charge to the 2nd card used. Without this `payment_method_uri`, the most recent card would be charged. IMPORTANT NOTES: Not all payment methods can be used this way. Current support includes: normal credit card gateways; Adyen_embedded; Amazon Pay; Bambora; CyberSource card-present / point-of-sale; PayPal Express Checkout Reference Transaction; Square; Stripe (via Connect). Some gateways will only use the last payment method for the customer for that gateway, even if you might be using a `payment_method_uri` from a transaction that had used an earlier payment method for that gateway. These include: PayPal Commerce Platform; PayPal Express Checkout Reference Transaction (deprecated); and Amazon Pay. IMPORTANT - For PayPal Express Checkout Reference Transaction the last payment method needs to be a subscription. If the payment method isn't a subscription, the API will throw an error when trying to charge the customer. If you're interested in this functionality and not sure if all of your chosen payment gateways are supported, please get in touch with Foxy support.	URL	Obtained from the `fx:payments` link relation of a transaction.
use_customer_shipping_address	This value determines how an attached customer's addresses should be handled in the event the cart resource is POSTed to. When `false`, the customer's billing address will be used for both the billing and shipping addresses. Defaults to `true`, so a customer's shipping address will be used if it exists.	Boolean	True or false, 1 or 0.
billing_, shipping_	You can override the address values populated by the `customer_uri`. Note that if you do so, you should explicitly set all `shipping_` and `billing_`, including blank values. For instance, if you PATCH to set a different address, ensure you pass through an empty `shipping_address2` value, or the existing value from the `customer_uri` will remain. Also note that if a `customer_uri` is added after addresses are set, the customer's billing and shipping addresses will overwrite what you have set explicitly, as noted above. Please see the `customer_addresses` documentation for the acceptable values.	Mixed	Mixed
template_set_uri	The full API URI of the template set for this cart, if one has been specified.	URL	Obtained from the self link relation of a template set.
language	The language defined by the template set being used.	String	Will use the language of your default template set if not supplied. languages
total_item_price	Total amount of the items in this cart.	Decimal	Read only
total_tax	Total amount of the taxes for this cart.	Decimal	Read only
total_shipping	Total amount of the shipping costs for this cart.	Decimal	(note: live shipping rate calculations do not currently work for this API)
total_future_shipping	If this cart has any shippable subscription items which will process in the future, this will be the total amount of shipping costs for those items.	Decimal	(note: live shipping rate calculations do not currently work for this API)
total_order	Total order amount of this cart including all items, taxes, shipping costs and discounts.	Decimal	Read only
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/carts/32",
            "title": "This Cart"
        },
        "fx:attributes": {
            "href": "https://api.foxycart.com/carts/32/attributes",
            "title": "Attributes for This Cart"
        },
        "fx:store": {
            "href": "https://api.foxycart.com/stores/8",
            "title": "This Store"
        },
        "fx:template_set": {
            "href": "https://api.foxycart.com/template_sets/1446",
            "title": "This Template Set"
        },
        "fx:customer": {
            "href": "https://api.foxycart.com/customers/8",
            "title": "This Customer"
        },
        "fx:items": {
            "href": "https://api.foxycart.com/carts/32/items",
            "title": "The Items for This Cart"
        },
        "fx:discounts": {
            "href": "https://api.foxycart.com/carts/32/discounts",
            "title": "Discounts for this Cart"
        },
        "fx:applied_coupon_codes": {
            "href": "https://api.foxycart.com/carts/32/applied_coupon_codes",
            "title": "Coupon Codes applied to this Cart"
        },
        "fx:custom_fields": {
            "href": "https://api.foxycart.com/carts/32/cart_custom_fields",
            "title": "The Custom Fields for this Cart"
        },
        "fx:create_session": {
            "href": "https://api.foxycart.com/carts/32/session",
            "title": "POST here to create a browser session link"
        }
    },
    "customer_uri": "https://api.foxycart.com/customers/8",
    "template_set_uri": "https://api.foxycart.com/template_sets/1446",
    "language": "english",
    "use_customer_shipping_address": true,
    "billing_first_name": "Grace",
    "billing_last_name": "Hopper",
    "billing_company": "",
    "billing_address1": "1234 Mulberry Dr.",
    "billing_address2": "#567",
    "billing_city": "MANHATTAN",
    "billing_state": "NY",
    "billing_postal_code": "10001",
    "billing_country": "US",
    "billing_phone": "",
    "shipping_first_name": "test1",
    "shipping_last_name": "test2",
    "shipping_company": "test3",
    "shipping_address1": "test4",
    "shipping_address2": "test5",
    "shipping_city": "Austin",
    "shipping_state": "TX",
    "shipping_postal_code": "78767",
    "shipping_country": "US",
    "shipping_phone": "",
    "total_item_price": 0,
    "total_tax": 0,
    "total_shipping": 0,
    "total_future_shipping": 0,
    "total_order": 0,
    "date_created": "2012-02-29T13:55:09-0800",
    "date_modified": null
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/carts/32" rel="https://api.foxycart.com/rels/cart">
  <link rel="self" href="https://api.foxycart.com/carts/32" title="This Cart"/>
  <link rel="https://api.foxycart.com/rels/attributes" href="https://api.foxycart.com/carts/32/attributes" title="Attributes for This Cart"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/8" title="This Store"/>
  <link rel="https://api.foxycart.com/rels/template_set" href="https://api.foxycart.com/template_sets/1446" title="This Template Set"/>
  <link rel="https://api.foxycart.com/rels/customer" href="https://api.foxycart.com/customers/8" title="This Customer"/>
  <link rel="https://api.foxycart.com/rels/items" href="https://api.foxycart.com/carts/32/items" title="The Items for This Cart"/>
  <link rel="https://api.foxycart.com/rels/discounts" href="https://api.foxycart.com/carts/32/discounts" title="Discounts for this Cart"/>
  <link rel="https://api.foxycart.com/rels/applied_coupon_codes" href="https://api.foxycart.com/carts/32/applied_coupon_codes" title="Coupon Codes applied to this Cart"/>
  <link rel="https://api.foxycart.com/rels/custom_fields" href="https://api.foxycart.com/carts/32/cart_custom_fields" title="The Custom Fields for this Cart"/>
  <link rel="https://api.foxycart.com/rels/create_session" href="https://api.foxycart.com/carts/32/session" title="POST here to create a browser session link"/>
  <customer_uri>https://api.foxycart.com/customers/8</customer_uri>
  <total_item_price>0</total_item_price>
  <total_tax>0</total_tax>
  <total_shipping>0</total_shipping>
  <total_future_shipping>0</total_future_shipping>
  <total_order>0</total_order>
  <date_created>2012-02-29T13:55:09-0800</date_created>
  <date_modified></date_modified>
</resource>

{
    "class": [
        "cart"
    ],
    "properties": {
        "customer_uri": "https://api.foxycart.com/customers/8",
        "template_set_uri": "https://api.foxycart.com/template_sets/1446",
        "language": "english",
        "total_item_price": 0,
        "total_tax": 0,
        "total_shipping": 0,
        "total_future_shipping": 0,
        "total_order": 0,
        "date_created": "2012-02-29T13:55:09-0800",
        "date_modified": null
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/carts/32"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/attributes"
            ],
            "href": "https://api.foxycart.com/carts/32/attributes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api.foxycart.com/stores/8"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/template_set"
            ],
            "href": "https://api.foxycart.com/template_sets/1446"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/customer"
            ],
            "href": "https://api.foxycart.com/customers/8"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/items"
            ],
            "href": "https://api.foxycart.com/carts/32/items"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/discounts"
            ],
            "href": "https://api.foxycart.com/carts/32/discounts"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/applied_coupon_codes"
            ],
            "href": "https://api.foxycart.com/carts/32/applied_coupon_codes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/custom_fields"
            ],
            "href": "https://api.foxycart.com/carts/32/cart_custom_fields"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/create_session"
            ],
            "href": "https://api.foxycart.com/carts/32/session"
        }
    ]
}

Conditional Link Relationships

If this cart has a subscription associated with it, it will include a subscription and a sub_token_url link relationship.

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
items
custom_fields
discounts
applied coupon codes

Modifiable Embedded Resources

The Cart resource also allows you to create Attributes, Custom Fields, Items, Item Options, and Item Attributes in one PUT request. This can save you a lot of time if you'd like to modify an entire cart all at once instead of having to POST to individual collections to add attributes/items/item options or PUT/PATCH individual resources to update them. By doing a PUT on the Cart resource with the embedded resources included, you can modify resources, add resources, and delete resources all in one HTTP action.

To modify embedded items and item options, include a zoom like ?zoom=items,items:item_options. For hal+json, you can then include the _embedded items and item_options in the document you PUT back to the cart, including any changes, additions or deletions. The same thing goes for hal+xml and the <resources> included there. Just be sure to include the rel="https://api.foxycart.com/rels/item" and rel="https://api.foxycart.com/rels/item_option" resource attributes in your XML as needed.

Supported embeddable resources currently include:

attributes
custom_fields
items
items:item_options
items:attributes
applied_coupon_codes

Example

Here's what an example PUT request would look like. Some things to note:

You first need to POST to the carts collection so the cart exists in the first place.
When you do this PUT, you'll need the ?zoom=items,items:item_options in the URL (including whichever embedded resources you're using from the list above).
Some values are calculated automatically (like the total_ values, subscription_next_transaction_date, etc.), so you can leave them as null (or they will be overridden).

{
  "_embedded": {
    "fx:attributes": [
        {
            "name": "cart attribute 1",
            "value": "value 1",
            "visibility": "public"
        },
        {
            "name": "cart attribute 2",
            "value": "value 2",
            "visibility": "public"
        }
    ],
    "fx:items": [
      {
        "item_category_uri": "https://api.foxycart.com/item_categories/10",
        "name": "Example Subscription",
        "price": 19.99,
        "quantity": 1,
        "quantity_min": 0,
        "quantity_max": 0,
        "weight": 4,
        "code": "xyz456",
        "parent_code": "",
        "discount_name": "Quantity Discount",
        "discount_type": "quantity_amount",
        "discount_details": "incremental|2-1|5-2|25-5",
        "subscription_frequency": "1m",
        "subscription_start_date": "2025-01-01",
        "subscription_next_transaction_date": null,
        "subscription_end_date": null,
        "is_future_line_item": true,
        "shipto": "",
        "url": "",
        "image": "",
        "length": 0,
        "width": 0,
        "height": 0,
        "expires": 0,
        "_embedded": {
          "fx:item_options": [
            {
              "name": "color",
              "value": "red",
              "price_mod": -10,
              "weight_mod": 0
            }
          ]
        }
      },
      {
        "item_category_uri": "https://api.foxycart.com/item_categories/10",
        "name": "Sprocket",
        "price": 100,
        "quantity": 2,
        "quantity_min": 0,
        "quantity_max": 0,
        "weight": 1,
        "code": "abc123",
        "parent_code": "",
        "discount_name": null,
        "discount_type": null,
        "discount_details": null,
        "subscription_frequency": null,
        "subscription_start_date": null,
        "subscription_next_transaction_date": null,
        "subscription_end_date": null,
        "is_future_line_item": false,
        "shipto": "",
        "url": "",
        "image": "http://placecorgi.com/100/200",
        "length": 0,
        "width": 0,
        "height": 0,
        "expires": 0,
        "_embedded": {
          "fx:item_options": [
            {
              "name": "size",
              "value": "xl",
              "price_mod": 0,
              "weight_mod": 2
            }
          ]
        }
      }
    ]
  },
  "customer_uri": "",
  "template_set_uri": "",
  "language": null,
  "use_customer_shipping_address": true,
  "billing_first_name": "Grace",
  "billing_last_name": "Hopper",
  "billing_company": "",
  "billing_address1": "1234 Mulberry Dr.",
  "billing_address2": "#567",
  "billing_city": "MANHATTAN",
  "billing_state": "NY",
  "billing_postal_code": "10001",
  "billing_country": "US",
  "billing_phone": "",
  "shipping_first_name": "test1",
  "shipping_last_name": "test2",
  "shipping_company": "test3",
  "shipping_address1": "test4",
  "shipping_address2": "test5",
  "shipping_city": "Austin",
  "shipping_state": "TX",
  "shipping_postal_code": "78767",
  "shipping_country": "US",
  "shipping_phone": "",
  "locale_code": null,
  "total_item_price": null,
  "total_tax": null,
  "total_shipping": null,
  "total_future_shipping": null,
  "total_order": null
}