Help: 3. Items

Help Portal » Knowledgebase » WhisperGifts API » 3. Items

Details on creating registry items via the API, as well as making changes, getting a list of all registry items, and deleting existing items.

Full read-write access is available to any items assigned to the authenticated user's registry. Be careful when updating or deleting items where the quantity remaining doesn't match the requested quantity, as it may lead to confusion with existing buyers.

Data Model

Note that fields may be provided in any order in both requests and responses.

idInteger; unique identifier for this item. Never changes and is never used for a different item. Used to identify the item for all detail, update, or delete requests. Generated automatically by WhisperGifts and cannot be supplied in an update or create message body.
name Short name of this product, eg Apple TV. Maximum 100 characters.
description Text. Longer description of the product, eg colour preferences, size and style, preferred brand, and so on. This is a large text field and has no reasonable length restriction.
comment Optional Text. Secondary details about the product or preferences, not shown to the purchaser until they are on the selection page. This is a large text field and has no reasonable length restriction.
price_min Optional Integer. Expected price for the item. If price_max is provided, this is the lower bounds of the expected price bracket. Respect the users' default currency.
price_max Optional Intege.r Upper bounds of expected price bracket for this item. This is in the users' default currency.
quantity Optional; default if not provided is 1. Integer. Number of this item the couple are requesting. If this is greater than 1, purchasers can select to buy 1 or more of this item (up to the value of quantity). Example: 4x bath towels are requested. A couple can buy 2 bath towels, and the registry will continue to request 2 bath towels for somebody else to select.
quantityremaining Read-only Integer. Identifies how many of this item are left. If it differs from quantity then somebody has already selected and purchased this item
url Optional Text, max 200 characters. Must be a correctly-formed URL. If this product has it's own website or recommended online seller, provide the URL here.
recommended_store Optional Text, max 100 characters. A store that the couple suggest the purchaser should buy this item for; we suggest you provide this for difficult-to-find or unique items.
priority Optional; default if not provided is 3. Integer between 1 and 5, inclusive. Items are shown with most desired items first (ie those with a priority of 5) and least desired (priority = 1) last. This is usually displayed on-screen as 1-5 stars.
category Integer ID of the category this item belongs to. See the API Category Documentation for further details. You must expose this to an end user as a name value per the Category resource API, however create and update requests must utilise the id integer.
category_name Read Only Text (max 100 characters). Name of the category relating to the assigned category. This is returned in responses to you for ease of display, however you cannot provide a category_name during create or update requests.
last_modified Read Only Timestamp noting when this item was last modified (or if never edited, when it was created). Timezone is Australian Eastern Standard Time. This cannot be provided during a create or update request; it is provided to you for convenience.

List

A paginated list of all items on the authenticated users' registry.

Request

curl -X GET "https://www.whispergifts.com/api/v0/items/" -H "API-Auth: [user_id]:[api_key]"

Response

{
    count: 85,
    per_page: 50,
    num_pages: 2,
    page: 1,
    objects: [
        {
            comment: "",
            price_max: null,
            description: "We *really* need a microwave oven as Tim doesn't know how to cook any other way!",
            quantity: 1,
            url: "",
            recommended_store: "",
            name: "Microwave Oven",
            priority: 3,
            last_modified: "2014-07-21T14:50:33.924404",
            price_min: null,
            category: 9,
            id: 204,
            category_name: "Appliances"
        },
        {
            comment: "",
            price_max: null,
            description: "We need a new doona - Sarah gets cold feet easily, so a nice warm one is necessary.",
            quantity: 1,
            url: "",
            recommended_store: "",
            name: "King-Size Doona",
            priority: 5,
            last_modified: "2014-02-06T14:55:43.830883",
            price_min: null,
            category: 7,
            id: 230,
            category_name: "Bed & Bath"
        },
        ....
    ]
}

Detail

A single item record, as identified by the provided ID.

Request

curl -X GET "https://www.whispergifts.com/api/v0/items/[id]/" -H "API-Auth: [user_id]:[api_key]"

Response

{
    comment: "",
    price_max: null,
    description: "We *really* need a microwave oven as Tim doesn't know how to cook any other way!",
    quantity: 1,
    url: "",
    recommended_store: "",
    name: "Microwave Oven",
    priority: 3,
    last_modified: "2014-07-21T14:50:33.924404",
    price_min: null,
    category: 9,
    id: 204,
    category_name: "Appliances"
}

Modify Existing Item

Any existing item can be modified, even if somebody has purchased it. You should be careful when editing items that have a quantityremaining that differs from the quantity as it signifies somebody has already chosen this item. Most apps should alert users to this fact.

When performing an update, the entire object must be provided. Any fields not returned will be assume to be null, which will raise an error if you try to leave out a required field.

Request

curl -X PUT "https://www.whispergifts.com/api/v0/items/[id]/" -H "API-Auth: [user_id]:[api_key]" -d '{
    comment: "Please avoid touch-screen models.",
    price_max: 250,
    description: "We *really* need a microwave oven as Tim doesn't know how to cook any other way!",
    quantity: 1,
    recommended_store: "David Jones",
    name: "Microwave Oven",
    priority: 2,
    price_min: 200,
    category: 9
}'

Response

An Item Detail record, as per the "Detail" view above.

{
    comment: "Please avoid touch-screen models.",
    price_max: 250,
    description: "We *really* need a microwave oven as Tim doesn't know how to cook any other way!",
    quantity: 1,
    recommended_store: "David Jones",
    name: "Microwave Oven",
    priority: 2,
    price_min: 200,
    category: 9,
    category_name: "Appliances",
    last_modified: "2014-07-21T14:50:33.924404",
    id: 204
}

Create New Item

All items will automatically be assigned to the authenticated users' registry. The created object is returned immediately, as if you had requested it directly. Note that the response will include the generated id which you can use in future requests if necessary.

Request

curl -X POST "https://www.whispergifts.com/api/v0/items/" -H "API-Auth: [user_id]:[api_key] -d '
{
    "name": "New item name goes here",
    "description": "A description of the item",
    "comment": "Shown to buyers at selection time, eg Thanks for our gift!",
    "price_min": 100,
    "price_max": 150,
    "quantity": 1,
    "url": "http://www.example.com",
    "recommended_store": "Your local department store",
    "priority": 2,
    "category": 9
}'

Response

An Item Detail record, as per the "Detail" view above.

{
    "name": "New item name goes here",
    "description": "A description of the item",
    "comment": "Shown to buyers at selection time, eg Thanks for our gift!",
    "price_min": 100,
    "price_max": 150,
    "quantity": 1,
    "url": "http://www.example.com",
    "recommended_store": "Your local department store",
    "priority": 2,
    "category": 9,
    "id": 31803,
    "category_name": "Appliances",
    "last_modified": "2014-07-21T14:50:33.924404",

Delete Item

Request

curl -X DELETE "https://www.whispergifts.com/api/v0/items/[id]/" -H "API-Auth: [user_id]:[api_key]"

Response

HTTP Response code 200 (OK) with a blank body. If an error is encountered, the message will be in the response body.