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

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 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
}