cart

Description

A transaction template is basically a cart which will be processed as a transaction each time the subscription runs.

Sandbox Example

You can interact with this resource and run actions against the sandbox API via our HAL Brower.

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)
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 process a cart into a transaction unless this value is set to a valid customer with an active default payment method. URL Obtained from the self link relation of a customer.
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",
    "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 Relationsips

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

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

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": "2018-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,
  "locale_code": null,
  "total_item_price": null,
  "total_tax": null,
  "total_shipping": null,
  "total_future_shipping": null,
  "total_order": null
}