Explanation

Expanding Objects

In order to limit the size of the responses and the number of API calls to the server, UltraCart supports expanding certain objects through the _expand query parameter. The best example of expansion is the item object, because items contain a large amount of data. Often programs want to query an item, but only a portion of it, make a change, and then update the item. REST expansion lets you indicate how you want the object expanded beyond the basic object on the retrieval request. This reduces the need to make additional API calls to fetch deeper information, as most REST APIs require. Then on the update API calls, if the object is only partially expanded, then only those portions of the object are updated, the rest of the object that exists on the server is left alone.

Using REST expansion will:

Make your REST API calls faster
Reduce the bandwidth consumed by your API calls
Provide simpler objects to work with

Each REST API that supports expansion will have the _expand parameter documented on the API call, listing the values that call accepts. The corresponding create/update REST APIs will handle receiving the partially expanded object without any special action on your part. For the full list per resource, see Available expansions by resource below.

note

The exact same expansion syntax used on the _expand parameter is also used in our webhook configuration to specify the amount of expansion for the objects that you receive notices on.

Example

Here is an example of a real-world _expand parameter from a WordPress plugin:

_expand=pricing,shipping.distribution_centers,content.multimedia.thumbnails[filter(100,100,"png", true),filter(360,360, "png", true)]

The sample expansion above tells the system that the call is interested in:

pricing
shipping
- distribution_centers (this contains the inventory information)
content
- multimedia
  - thumbnails (filtered to 100x100 square PNGs and 360x360 square PNGs)

Basic item response

{
    "merchant_item_oid": 875851,
    "merchant_id": "DEMO",
    "merchant_item_id": "Baseball Bat",
    "description": "Wood Baseball Bat",
    "description_translated_text_instance_oid": 649867,
    "last_modified_dts": "2016-08-11T16:14:46-04:00",
    "creation_dts": "2009-01-14T18:30:42-05:00"
}

Expanded item response

{
    "merchant_item_oid": 875851,
    "merchant_id": "DEMO",
    "merchant_item_id": "Baseball Bat",
    "description": "Wood Baseball Bat",
    "description_translated_text_instance_oid": 649867,
    "last_modified_dts": "2016-08-11T16:14:46-04:00",
    "creation_dts": "2009-01-14T18:30:42-05:00",
    "pricing": {
        "cost": 5.50
    },
    "shipping": {
        "distribution_centers": [{
            "distribution_center_oid": 29522,
            "distribution_center_code": "DFLT",
            "inventory_level": 4,
            "handles": true,
            "allocated_to_placed_orders": 2,
            "allocated_to_shopping_carts": 0,
            "available_to_allocate": 2
        }]
    },
    "content": {
        "view_url": "http://www.testajax.com/catalog/DEMO/products/facebook/fb-single/Baseball Bat.html",
        "multimedia": [{
            "merchant_item_multimedia_oid": 239393,
            "file_name": "baseballbat.jpg",
            "description": "Baseball Bat",
            "url": "//secure.ultracart.com/itemmultimedia/DEMO/BASEBALL BAT/baseballbat.jpg",
            "type": "Image",
            "code": "default",
            "width": 108,
            "height": 120,
            "thumbnails": [{
                "height": 100,
                "width": 100,
                "http_url": "http://ultracartthumbs.s3.amazonaws.com/1363101689475/DEMO/0/1/100-100-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "https_url": "https://s3.amazonaws.com/ultracartthumbs/1363101689475/DEMO/0/1/100-100-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "square": true
            }, {
                "height": 360,
                "width": 360,
                "http_url": "http://ultracartthumbs.s3.amazonaws.com/1472069542543/DEMO/0/1/360-360-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "https_url": "https://s3.amazonaws.com/ultracartthumbs/1472069542543/DEMO/0/1/360-360-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "square": true
            }]
        }]
    }
}

Available expansions by resource

Nesting is expressed with a dot, so shipping.tracking_number_details expands tracking_number_details inside shipping. Requesting a nested value does not imply its parent, so list each level you want.

Resources not listed here accept _expand but do not publish a value list. Check the _expand parameter on the specific endpoint in the API reference.

Auto Orders

58 expansions.

items
items.future_schedules
items.simple_schedule
logs
management
original_order
original_order.affiliate
original_order.affiliate.ledger
original_order.auto_order
original_order.billing
original_order.buysafe
original_order.channel_partner
original_order.checkout
original_order.coupon
original_order.current_stage_histories
original_order.customer_profile
original_order.digital_order
original_order.edi
original_order.fraud_score
original_order.gift
original_order.gift_certificate
original_order.internal
original_order.item
original_order.linked_shipment
original_order.marketing
original_order.payment
original_order.payment.transaction
original_order.quote
original_order.salesforce
original_order.shipping
original_order.summary
original_order.taxes
rebill_orders
rebill_orders.affiliate
rebill_orders.affiliate.ledger
rebill_orders.auto_order
rebill_orders.billing
rebill_orders.buysafe
rebill_orders.channel_partner
rebill_orders.checkout
rebill_orders.coupon
rebill_orders.customer_profile
rebill_orders.digital_order
rebill_orders.edi
rebill_orders.fraud_score
rebill_orders.gift
rebill_orders.gift_certificate
rebill_orders.internal
rebill_orders.item
rebill_orders.linked_shipment
rebill_orders.marketing
rebill_orders.payment
rebill_orders.payment.transaction
rebill_orders.quote
rebill_orders.salesforce
rebill_orders.shipping
rebill_orders.summary
rebill_orders.taxes

Checkout

27 expansions.

affiliate
billing
buysafe
checkout
coupons
customer_profile
gift
gift_certificate
items
items.attributes
items.multimedia
items.multimedia.thumbnails
items.physical
marketing
payment
settings.billing.provinces
settings.gift
settings.shipping.deliver_on_date
settings.shipping.estimates
settings.shipping.provinces
settings.shipping.ship_on_date
settings.taxes
settings.terms
shipping
summary
taxes
upsell_after

Customers

14 expansions.

attachments
billing
cards
cc_emails
loyalty
orders_summary
pricing_tiers
privacy
quotes_summary
reviewer
shipping
software_entitlements
tags
tax_codes

Items

47 expansions.

accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
identifiers
instant_payment_notifications
internal
kit_definition
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
revguard
reviews
reviews.individual_reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member

Orders

28 expansions.

affiliate
affiliate.ledger
auto_order
billing
buysafe
channel_partner
checkout
coupon
current_stage_histories
customer_profile
digital_order
edi
fraud_score
gift
gift_certificate
internal
item
linked_shipment
marketing
payment
payment.transaction
quote
salesforce
shipping
shipping.tracking_number_details
summary
taxes
utms

Was this page helpful?

Example​

Available expansions by resource​

Auto Orders​

Checkout​

Customers​

Items​

Orders​