Listing Carts

This documentation has moved to the Spark Platform website. Please click here to view.

The Listing Carts service allows a list of listing carts to be retrieved for the current user, individual listings to be added and removed from carts, and a list of carts to be retrieved based on whether the carts contain a specific listing.

  1. Applicable API Key Roles
  2. Authentication
  3. Available Services
    1. Listing Carts
    2. Individual Listing Cart
    3. Portal Carts (IDX role with portal permissions only)
  4. Request and Response Details
    1. GET Request and Response for Listing Carts
    2. GET Response for All Carts Containing a Specific Listing
    3. POST Request and Response for Listing Carts
    4. GET Request and Response for an Individual Listing Cart
    5. POST and PUT Request for an Individual Listing Cart
    6. DELETE Request for an Individual Listing Cart
    7. POST, PUT, and DELETE Response for an Individual Listing Cart

Applicable API Key Roles

This service is available to API keys with IDX roles with both IDX and portal permissions. Carts accessible to this service through the IDX role are the agent’s; the portal role provides access to contact carts. More information about roles may be found here.

Authentication

Requests must be authenticated according to these instructions or HTTP 401 (Unauthorized) will be returned.

Available Services

Listing Carts

URI: /<API Version>/listingcarts/

This URI is used to retrieve all carts for a user.

URI: /<API Version>/listingcarts/for/listing/XX

This URI is used to retrieve all carts for a user that contain the listing specified by XX.

URI: /<API Version>/listingcarts/portal

This URI is used to retrieve all portal carts (Recommended, Favorites, Possibilities, Rejects, Removed) for API keys that are using an IDX role and have portal permissions (i.e. have authenticated the portal user via OAuth).

HTTP Method Description
GET Retrieves carts for the user. Responses are paginated using the standard pagination syntax.
POST Creates a cart, for non-portal carts.
PUT, DELETE Returns HTTP 405 (Method Not Allowed). Not implemented.

GET Request and Response

There are no additional parameters on the GET request. Below is a sample response. This is returned for the /<API Version>/listingcarts/ service. If any of the carts are portal carts, then an additional PortalCartType attribute is returned matching the name of the portal cart (Recommended, Favorites, etc.) This attribute may be used to determine if the cart is one of the special carts that corresponds to one of the “smiley face” icons in the portal user interface.

Responses are paginated using the standard pagination syntax.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listingcarts/20100912153422758914000000",
                "Id": "20100912153422758914000000",
                "Name": "My Listing Cart",
                "ListingCount": 10 // number of listings in that cart
            },
            {
                "ResourceUri": "/vX/listingcarts/20110112133422752751000000",
                "Id": "20110112133422752751000000",
                "Name": "My Other Listing Cart",
                "ListingCount": 15
            }
        ]
    }
}

GET Response for All Carts Containing a Specific Listing

The response is similar to the previous response, except there is an array called ListingIds returned that indicate which listings were in what cart. This is the response used for the /<API Version>/listingcarts/for/listing/XX service, when determining if listings are in specific carts.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listingcarts/20100912153422758914000000",
                "Id": "20100912153422758914000000",
                "Name": "My Listing Cart",
                "ListingCount": 10, // number of listings in that cart,
                "ListingIds": [     // IDs of listings that are in this cart
                    "20110112133422752751000000"
                ]
            },
            {
                "ResourceUri": "/vX/listingcarts/20110112133422752751000000",
                "Id": "20110112133422752751000000",
                "Name": "My Other Listing Cart",
                "ListingCount": 15,
                "ListingIds": [
                    "20110112133422752751000000"
                ]
            }
        ]
    }
}

POST Requests

For POST requests, one or more listing IDs is required in order to create a cart. A unique cart name is required as well; if the cart already exists for the current user, an error will be returned.

The request body should be formatted as follows, putting each listing ID in its own array item. A listing ID typically looks like 20110112133422752751000000.

{
    "D": {
      "ListingCarts": [{
        "Name": "My Cart's Name",
        "ListingIds": [
            "20110112234857732941000000",
            "20110302120238448431000000",
            "20110510011212354751000000"
        ]
      }]
  }
}

POST Response

The standard success/fail response format with resource creation is returned.

Individual Listing Cart

URI: /<API Version>/listingcarts/XX

XX is the ID of a listing cart, such as 20110112133422752751000000, returned by services that supply listing cart IDs.

HTTP Method Description
GET Returns information about an individual listing cart.
POST Adds one or more listings to a cart.
PUT Replaces the contents of a listing cart with a list of listing IDs.
DELETE Either deletes the listing cart or deletes one or more listings in the listing cart.

GET Request and Response

There are no additional parameters on the GET request. Below is a sample response.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listingcarts/20110112133422752751000000",
                "Id": "20110112133422752751000000",
                "Name": "My Other Listing Cart",
                "ListingCount": 15
            }
        ]
    }
}

POST and PUT Requests

For POST and PUT requests, one or more listing IDs is required. If the request body is blank on any of these requests, an error will be returned.

The request body should be formatted as follows, putting each listing ID in its own array item. A listing ID typically looks like 20110112133422752751000000.

{
    "D": {
        "ListingIds": [
            "20110112234857732941000000",
            "20110302120238448431000000",
            "20110510011212354751000000"
        ]
    }
}

DELETE Requests

DELETE requests allow deletion of the entire cart or individual listings within the cart. To delete the entire cart, send a request to /vX/listingcarts/(cart ID); for example, /v1/listingcarts/20100912153422758914000000 .

To delete individual listings in a cart, send a DELETE to a URI of this format: /vX/listingcarts/(cart ID)/listings/(cart ID) . For example:/v1/listingcarts/20100912153422758914000000/listings/20111205154351948672000000 . Multiple listings may be deleted at once by sending a comma separated list of listing IDs for the last parameter.

POST, PUT, and DELETE Response

The standard success/fail response format without resource creation is returned.

Comments on this entry are closed.