attributes

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.

Sandbox Example

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

Actions

GET
View a list of attributes
POST
Create a new attribute, or create multiple new attributes
PATCH
Create new attributes and update existing attributes
PUT
Create new attributes by replacing all existing attributes
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:attributes": [...]
  },
  "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/attribute">
  ...
  </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: attribute

Description

An attribute is a non-standard property that can be applied to multiple resources such as a client, user, store, transaction, cart, subscription, shipment, item, and customer. You can set the visibility to control whether or not other client implementations can also view the property or if that property should not be visible unless connected with the proper client credentials.

Client Attribute Restrictions: To modify, view or create a client attribute, you must be connected to the API using an OAuth token which has client_full_access scope.

User Attribute Restrictions: To modify, view or create a user attribute, you must be connected to the API using an OAuth token which has user_full_access scope.

Sandbox Example

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

Actions

GET
View a attribute
PATCH
Update a attribute (send only the properties you want to modify)
PUT
Replace a attribute (send the entire representation)
DELETE
Delete a attribute
HEAD
Get just the header response
OPTIONS
Get a response explaining which HTTP methods are supported

Properties

Property Description Type Constraints
visibility Controls who can see this attribute. Public attributes can be shown to anyone, including customers. Private attributes are more suitable for configuration or technical details which are irrelevant to the public. Restricted attributes can only be viewed by the OAuth client who creates them. String public, private or restricted. Defaults to private. Can not be modified once set.
name The name of this attribute. String Required. 500 characters or less.
value The value of this attribute. String Required. 1000 characters or less.
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/store_attributes/1002",
            "title": "This store attribute"
        },
        "fx:store": {
            "href": "https://api.foxycart.com/stores/66",
            "title": "This Store"
        }
    },
    "visibility": "private",
    "name": "Hours",
    "value": "9am to 5pm",
    "date_created": "2013-08-05T14:15:59-0700",
    "date_modified": "2013-08-05T14:15:59-0700"
}
<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/store_attributes/1002" rel="https://api.foxycart.com/rels/attribute">
  <link rel="self" href="https://api.foxycart.com/store_attributes/1002" title="This store attribute"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/66" title="This Store"/>
  <visibility>private</visibility>
  <name>Hours</name>
  <value>9am to 5pm</value>
  <date_created>2013-08-05T14:15:59-0700</date_created>
  <date_modified>2013-08-05T14:15:59-0700</date_modified>
</resource>
{
    "class": [
        "attribute"
    ],
    "properties": {
        "visibility": "private",
        "name": "Hours",
        "value": "9am to 5pm",
        "date_created": "2013-08-05T14:15:59-0700",
        "date_modified": "2013-08-05T14:15:59-0700"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/store_attributes/1002"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api.foxycart.com/stores/66"
        }
    ]
}

Zoomable Resources

This resource has no linked resources which can be "zoomed" in on, filtered and embedded within this resource.

Creating & Updating Multiple Attributes in a Single Request

  • There is a limit of 20 attributes per request, when doing POST, PATCH, or PUT operations.

Examples

POST

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

  • POST will always create new attributes, regardless if you already have an attribute with that name. (Multiple attributes with the same name are allowed, though this may not always be what you intend.)
  • Because of this, PATCH is generally preferred, unless your use case necessitates multiple attributes with the same name.
[
    {
        "name": "name_value_one",
        "value": "value_one"
        "visibility": "public"
    },
    {
        "name": "name_value_two",
        "value": "value_two"
    },
    {
        "name": "name_value_three",
        "value": "value_three"
    },
    {
        "name": "name_value_four",
        "value": "value_four",
        "visibility": "public"
    }
]

PUT

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

  • PUT will first delete all attributes that the client has access to (ie. public, private, and any restricted attributes created by the client). Then it will create all the attributes passed in the request.
[
    {
        "name": "name_value_one",
        "value": "value_one",
        "visibility": "public"
    },
    {
        "name": "name_value_two",
        "value": "value_two",
        "visibility": "public"
    },
    {
        "name": "name_value_three",
        "value": "value_three",
        "visibility": "public"
    },
    {
        "name": "name_value_four",
        "value": "value_four"
    }
]

PATCH

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

  • Attributes are matched by name. Any existing attributes with named passed in a PATCH request will be updated.
  • Attributes that don't exist (ie. for which there is no existing attribute with the same name value) will be crated.
  • If there are two or more attributes with the same name exist in the payload, the API will throw an error.
  • Because a PATCH will not create duplicate attributes with the same name values, it is preferable to POST for most use cases.
[
    {
        "name": "name_value_one",
        "value": "value_one",
        "visibility": "public"
    },
    {
        "name": "name_value_two",
        "value": "value_two",
        "visibility": "public"
    },
    {
        "name": "name_value_three",
        "value": "value_three",
        "visibility": "public"
    },
    {
        "name": "name_value_four",
        "value": "value_four",
        "visibility": "public"
    }
]