Warning |
---|
This is Version 1 of the UltraCart REST API. It is now legacy. It will remain forever, but no new development will be done. Please see Version 2 for new development. Version 2 contains language specific SDKs, more functionality, and reduced API call counts. Version 2 Main Documentation Version 2 Supplemental Documentation |
Warning |
---|
Additional Note, August 2020: To prevent anyone from using this code in a new installation, several key samples have been removed. These samples referred to php scripts that are no longer compatible with the UltraCart engine. You should not be using this javascript anymore. This documentation exists only for a reference for old legacy implementations. |
Table of Contents | ||
---|---|---|
|
...
The UltraCart REST API aims to be a lightweight protocol for tying a checkout page(s) to the UltraCart back end.
Here are the demos
Tip | |||||||||
---|---|---|---|---|---|---|---|---|---|
There are simple examples of all the major REST calls found here: https://secure.ultracart.com/merchant/integrationcenter/checkoutapi_v3/demo1.html Please notice that the script is running on secure.ultracart.com, so it doesn't suffer any cross-domain restrictions. As such, the urls are all relative (/rest/cart). If you attempt to run a demo on your own machine, you'll need to install a proxy script, found here: https://github.com/UltraCart/responsive_checkout/blob/master/rest_proxy.php After installing it, you need to adjust your url. Notice the difference below between line 3 and 4.
|
Merchant ID Required
...
Every call needs a merchant id (our merchant id is DEMO)
. We need to know who you are. There are three ways to provide the merchant id to the server:
- Query Parameter:
_mid=DEMO
- HTTP Header:
'X-UC-Merchant-Id': 'DEMO'
- Cookie named
UltraCartMerchantId
Most of the examples below use the http header since it's easy to use with jQuery. If you wished to do it for all your ajax calls, you could execute this javascript:
jQuery.ajaxSetup({ cache: false, headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"});
However, that makes each call less atomic (and jQuery doesn't recommend it). Still, it's an option and may work well with your site.
If you receive an error "Missing Merchant ID", you've forgotten to do one of the above.
Now, in case you're wondering why the three methods use different names...
- We made the query parameter as short as possible to keep the urls as short as possible. We used an underscore to denote "meta data" to the call.
- We follow common practices for naming custom http headers. While the X- prefix is officially out of vogue, we still think it looks cool.
- The cookie 'UltraCartMerchantId' is used in hundred of existing UltraCart checkout pages. So it made sense to stick with that cookie name.
Where are the errors?
Warning |
---|
When something doesn't work or you get an error, open your browser console and view the headers. Look for the error. then fix it. Can't? Then get on github.com. Ask for help here. |
Note Regarding Support for API
...
title | API troubleshooting |
---|
...
Merchant ID Required
Info |
---|
Every call needs a merchant id (our merchant id is
Most of the examples below use the http header since it's easy to use with jQuery. If you wished to do it for all your ajax calls, you could execute this javascript:
However, that makes each call less atomic (and jQuery doesn't recommend it). Still, it's an option and may work well with your site. If you receive an error "Missing Merchant ID", you've forgotten to do one of the above. Now, in case you're wondering why the three methods use different names...
|
Where are the errors?
Warning |
---|
When something doesn't work or you get an error, open your browser console and view the headers. Look for the error. then fix it. Can't? Then get on github.com. Ask for help here. |
Note Regarding Support for API
Info | ||
---|---|---|
| ||
UltraCart's free support does not cover API development questions or troubleshooting of custom checkout pages. Additional API support and troubleshooting services can be purchased at $100/hr (1 hour minimum) via UltraCart Professional Services. (Scheduling of paid for support will be determined by Professional Services personnel.) |
...
Note | |||
---|---|---|---|
/rest/cart/checkout is NOT THE END! It's the beginning of the end. If the response from checkout has no errors, you must redirect the browser to the url found in checkoutResonse.redirectToUrl. That finishes the order. Any errors during that phase (card declined) will send the browser back to checkoutRequest.redirectOnErrorUrl, which is usually set to your checkout page. It's a circle, one that handles shipping companies and payment gateway timeouts without timing out the browser. It also handles any upsell gauntlets. So make sure you follow the redirect! Code Block | gauntlets. So make sure you follow the redirect!
|
Do this or you'll never complete an order...
...
Name | Design Goal | Location | Comments | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
responsive checkout | single page checkout, mobile friendly | https://github.com/UltraCart/responsive_checkout | |||||||||
two page trial | simple, geared toward trial offers | coming soonwordpress plugin | wordpress | coming soon | drupal plugin | drupal | coming soon | joomla plugin | joomla | coming soon |
Object Model
These json objects are used with the Cart REST API. The documentation below is shared with checkout versions 1.0 and 2.0. So you will see references to those libraries as well. Please consult the API section below the REST specific usage.
...
Field | Type | Comment | ||||
cartId | string | The unique ID for the cart. This needs to be stored as a cookie on the customer's browser so that the cart can be retrieved. | ||||
merchantId | string | The char(5) merchant designation (created during sign up) | ||||
errors | string[] | an array of errors returned from a call. This property should always be consulted after a call returns and messages displayed to the end customer. | ||||
advertisingSource | string | Advertising source the customer selected or entered. | ||||
affiliateId | string | The ID of the affiliate associated with this cart. You can set this field to manually assign an order to a specific affiliate. If no affiliate is associated with the order then this field will be null. | ||||
affiliateSubId | string | The Sub ID of the affiliate associated with this cart. The same comments for affiliateId apply to this field as well. | ||||
amazonMerchantId | string | The merchant's Amazon Seller ID as configured in the UltraCart system. | ||||
amazonOrderReferenceId | string | The reference id provided by Amazon once the customer has initiated checkout with them. If this is non-null and cart.paymentMethod is "Amazon", the order will be processed through Amazon.
| ||||
amazonWidgetUrl | string | The url for the amazon widget script. This will be production or sandbox depending on your UltraCart configuration.
| ||||
amazonButtonUrl | string | The url for the amazon button script. This will be production or sandbox depending on your UltraCart configuration. | ||||
arbitraryShippingHandlingTotal | number | Override field allowing merchant to override the shipping and handling calculated by the system. To use this field, the Shipping and Handling must be configured to allow overrides. | ||||
arbitraryTax | number | Override field allowing merchants to override calculated tax. To use this field, the Tax must be configured to allow overrides. | ||||
arbitraryTaxRate | number | Override field allowing merchants to override calculated tax rate. To use this field, the Tax must be configured to allow overrides. | ||||
arbitraryTaxableSubtotal | number | Override field allowing merchants to override the taxable subtotal. To use this field, the Tax must be configured to allow overrides. | ||||
baseCurrencyCode | string | The default currency code for the merchant. For most merchants, this will be USD, but can be changed in the merchant's configuration. see also currencyCode Valid values are: AUD Australian Dollar | ||||
billToAddress1 | string | Bill to address line 1 | ||||
billToAddress2 | string | Bill to address line 2 | ||||
billToCity | string | Bill to city | ||||
billToCompany | string | Bill to company | ||||
billToCountry | string | Bill to country. Must be a valid country name from the getAllowedCountries() API call. | ||||
billToDayPhone | string | Bill to day phone | ||||
billToEveningPhone | string | Bill to evening phone | ||||
billToFirstName | string | Bill to first name | ||||
billToLastName | string | Bill to last name | ||||
billToPostalCode | string | Bill to postal code | ||||
billToState | string | Bill to state | ||||
billToTitle | string | Bill to title | ||||
buysafeBondAvailable | boolean | buySAFE bond availability | ||||
buysafeBondCost | number | Cost of the buySAFE bond (for buySAFE merchants only) | ||||
buysafeBondFree | number | True if the buySAFE bond is free to the customer | ||||
buysafeBondWanted | boolean | True if the customer has opted in to a buySAFE bond | ||||
buysafeCartDisplayText | string | The sales text to display by the buySAFE control | ||||
buysafeCartDisplayUrl | string | The URL to link the sales text to so the customer can learn more about buySAFE.string | Bill to title | |||
ccEmail | string | CC Email address | ||||
collectCreditCardVerificationNumber | boolean | True if the CVV2 should be collected for this merchant. | ||||
comments | string | customer comments. this is usually collected via a textarea field. Added 12/2/2013 | ||||
coupons | CartCoupon[ ] | Coupons that have been applied to the cart. | ||||
creditCardExpirationMonth | Integer | Credit card expiration month 1 = January 12 = December | ||||
creditCardExpirationYear | integer | Credit card expiration year. Must be a four digit year. | ||||
creditCardNumber | string | Credit card number
| ||||
creditCardToken | string | Credit card token (if you are using a tokenizing gateway like Stripe.com) | ||||
creditCardType | string | Type of credit card. See the CREDIT_CARD_TYPE_ constants in the checkoutapi.js file for valid values. | ||||
creditCardTypes | string[] | An array of credit card types (Visa, Mastercard, etc.) that are currently accepted. Used to generate drop down lists. | ||||
creditCardVerificationNumber | string | Credit card verification number 4 digits for American Express and 3 digits for all other types of credit cards. | ||||
currencyCode | string | The currency of the cart. The default is the merchant default. Change this value to set the currency of the cart to a different value. If the first item added to the cart has a default currency other than USD, the cart currency will change to match the first item automatically. (see also baseCurrencyCode) | ||||
customerProfileCreditCardId | Integer | The oid (object id) of a stored (on file) credit card to use with the checkout. Supply this to us a credit card on file. When this is value is passed in to an update call, it will return back a cart with all the card information populated (number masked). If you wish to remove a stored credit card from an order, set this property to 0 (zero). That will reset it. The credit card id is found in the cart object of a logged in customer at
| ||||
customField1 | string | A custom field to store up to 50 characters. | ||||
customField2 | string | A custom field to store up to 50 characters. | ||||
customField3 | string | A custom field to store up to 50 characters. | ||||
customField4 | string | A custom field to store up to 50 characters. | ||||
customField5 | string | A custom field to store up to 50 characters. | ||||
customField6 | string | A custom field to store up to 50 characters. | ||||
customField7 | string | A custom field to store up to 50 characters. | ||||
customerProfile | CustomerProfile | If loggedIn, this variable will contain the CustomerProfile for the current session. | ||||
deliveryDate | Date | Delivery date (optional) | ||||
string | Email address | |||||
emailConfirm | string | Second copy of email address used to confirm the customer entered it correctly | ||||
exchangeRate | number | The conversion rate between merchant default and local currencies | ||||
giftCertificate | string | Gift certificate code | ||||
giftCertificateAmount giftCertificateAmountLocalized giftCertificateAmountLocalizedFormatted | number number string | Gift certificate amount | ||||
giftCertificateRemainingBalanceAfterOrder giftCertificateRemainingBalanceAfterOrderLocalized giftCertificateRemainingBalanceAfterOrderLocalizedFormatted | number number string | The balance remaining the gift certificate if its initial value was greater than the cart total. | ||||
giftCharge giftChargeLocalized giftChargeLocalizedFormatted | number number string | Gift charge | ||||
giftEmail | string | Email address of the person receiving this purchase as a gift | ||||
giftEmail | string | Gift Email address | ||||
giftMessage | string | Gift message | ||||
giftWrapCost giftWrapCostLocalized giftWrapCostLocalizedFormatted | number number string | Gift wrap cost | ||||
hasAmazon | boolean | This will be true if the merchant has "Pay with Amazon" configured properly AND the cart supports it, i.e. the items can be process through Amazon Payments. If the cart is empty, this will be false, since you can't checkout with zero items. | ||||
hasPayPal | boolean | True if the merchant has PayPal enabled. | ||||
ipAddress | string | IP Address of the customer. Used for geo-location of shipping estimates. | ||||
items | CartItem[ ] | All the items in the cart. | ||||
liftGate | boolean | True if this purchase will require delivery by lift gate, false (default) otherwise. | ||||
loggedIn | boolean | true if a customer profile is active, false if otherwise | ||||
mailingListOptIn | boolean | Whether the customers wants to receive news and special offers via email. | ||||
needShipping | boolean | true if the cart needs shipping calculated. | ||||
needPayment | boolean | true if the cart should collect payment. This may seem a little useless since it would stand to reason that any time the total is greater than zero payment should be collected. However, there are outside cases where this flag makes the difficult easy. For example, if a customer purchases a free product that is tied to an auto order, then the total of the cart is zero, but payment must be collected for the recurring item to be charged against. This flag makes those scenarios automatic where they would otherwise be impossible to determine without some hardcoded measures. Note: Added January 2014. Only available with the REST API | ||||
password | string | the password is only used during the login (or register) process to log a customer in. It is not populated on any returned objects, so it is lost (purposely) after login. Constraints: 30 characters max. | ||||
payPalButtonAltText | string | Alt text to use on the PayPal express checkout image | ||||
payPalButtonUrl | string | URL of the PayPal express checkout image | ||||
payPalCompatible | boolean | True if this cart is compatible with PayPal | ||||
paymentMethod | string | Type of payment method. See the PAYMENT_METHOD_ constants in the checkoutapi.js file for valid values. | ||||
purchaseOrderNumber | string | Purchase order number | ||||
rtgCode | string | Specify the Rotating Transaction Gateway for this checkout experience. | ||||
screenBrandingThemeCode | string | The screen branding theme associated with the cart. | ||||
shipOnDate | Date | Ship on date (optional) | ||||
shipToAddress1 | string | Ship to address line 1 | ||||
shipToAddress2 | string | Ship to address line 2 | ||||
shipToCity | string | Ship to city | ||||
shipToCompany | string | Ship to company | ||||
shipToCountry | string | Ship to country. Must be a valid country name from the getAllowedCountries() API call. | ||||
shipToFirstName | string | Ship to first name | ||||
shipToLastName | string | Ship to last name | ||||
shipToPhone | string | Ship to phone | ||||
shipToPostalCode | string | Ship to postal code | ||||
shipToResidential | boolean | True if the address is residential. | ||||
shipToState | string | Ship to state | ||||
shipToTitle | string | Ship to title | ||||
shippingHandling shippingHandlingLocalized shippingHandlingLocalizedFormatted | number number string | Shipping and handling cost
| ||||
shippingHandlingDiscount shippingHandlingDiscountLocalized shippingHandlingDiscountLocalizedFormatted | number number string | Shipping and handling discount (because of coupon) | ||||
shippingHandlingWithDiscount shippingHandlingWithDiscountLocalized shippingHandlingWithDiscountLocalizedFormatted | number number string | Shipping and handling cost after discount applied. | ||||
shippingMethod | string | Shipping method | ||||
specialInstructions | string | Special instructions for delivery. | ||||
storeCreditCard | boolean | If true and the customer has logged in (cart.customerProfile != null and cart.loggedIn == true), then the credit used during the purchase is stored in the customer's profile. UltraCart considers it good ettiquette to prompt the user to store their credit card. On the normal checkout pages, this is done via a checkbox. | ||||
subtotal subtotalLocalized subtotalLocalizedFormatted | number number string | Subtotal | ||||
subtotalDiscount subtotalDiscountLocalized subtotalDiscountLocalizedFormatted | number number string | Subtotal discount (because of coupon) | ||||
subtotalWithDiscount subtotalWithDiscountLocalized subtotalWithDiscountLocalizedFormatted | number number string | Subtotal after discounts have been applied | ||||
surcharge surchargeLocalized surchargeLocalizedFormatted | number number string | Credit card surcharge amount | ||||
tax taxLocalized taxLocalizedFormatted | number number string | Tax | ||||
taxCounty | string | The tax county assigned to this customer. See method getTaxCounties(). | ||||
taxExempt | number | True if the customer is tax exempt | ||||
taxRate | number | Tax rate | ||||
taxableSubtotal taxableSubtotalLocalized taxableSubtotalLocalizedFormatted | number number string | Taxable subtotal | ||||
taxableSubtotalDiscount taxableSubtotalDiscountLocalized taxableSubtotalDiscountLocalizedFormatted | number number string | Taxable subtotal discount (because of coupons) | ||||
taxableSubtotalWithDiscount taxableSubtotalWithDiscountLocalized taxableSubtotalWithDiscountLocalizedFormated | number number string | Taxable subtotal after discounts. | ||||
total totalLocalized totalLocalizedFormatted | number number string | Total | ||||
upsellPathCode | string | A string dictating which upsell path code should be followed. By specifying this path, this will override any upsells normally followed based on the cart contents. Note: Added Dec, 2013, Available only for the Checkout REST API. |
CartCoupon
Include Page | ||||
---|---|---|---|---|
|
...
Field | Type | Description | ||
---|---|---|---|---|
cart | Cart | The cart object | ||
errorParameterName | string | The name of the http query parameter that should be used to denote errors. There are two places for errors. During the API call, and after the page has changed. This name is used for the latter. Once the location has handed off to the Background Processor for credit card validations, the user is shown the "Please Wait" screen. If there are errors at this point, the customer is redirected to an error page (denoted by errorReturnToUrl). The error page is typically the checkout page, and the page contains code to look for any errors in the url and display them appropriately. | ||
errorReturnToUrl | string | The page that is called when there are second-stage errors with the checkout. | ||
secureHostName | string | If the site is not running under Requirements: Any host name passed in via secure host name must be a registered host name with your account. This means you'll need to have the host name registered and a valid SSL certificate on file with UltraCart for that host name to be accepted. If the host name doesn't exist on your account, your default host name will be used. We make this requirement to avoid security issues that might arise from accepting any host name provided. What secureHostName does: Passing in a secureHostName will affect the checkout handoff url. It be will used like this: "https://" + secureHostName + "/cgi-bin/UCCheckoutHandoff? The handoff is the portion of the checkout experience where UltraCart takes over and handles things like shipping estimate timeouts, long payment gateway transaction times, retries, etc. What secureHostName does not: The secure host name does NOT affect the receipt page. The receipt page is handled by the screen branding theme. It's like that for many legacy reasons, so you'll just need to manage the receipt page separately. If you need a custom receipt page served with a different host name, configure it in your screen branding section set the cart.screenBrandingThemeCode to the screen branding code. For reference, see: | ||
payPalBillMeLater | boolean | set this to true if you wish to use PayPal Bill Me Later. The cart.paymentMethod must be equal to "PayPal" for the server to even look at this flag. | ||
payPalMaximumUpsellRevenue | decimal | If you are implementing a custom upsell gauntlet and the payment method is PayPal, you need to specify the maximum amount of upsell revenue possible. Added January 2014 | ||
payPalReturnUrl | string | This is the full url of your first custom upsell page. Need the info below for details.
Added January 2014 | ||
forceFinalizeOrder | boolean | Scope: PayPal checkout with custom upsell gauntlet. This flag needs to be set to true during the second call to checkout after a custom upsell using PayPal. That's the only time it needs to be set. When set, it avoids sending the customer to the PayPal authentication screen again.
|
...
Info | ||
---|---|---|
Using PayPal with a custom upsell gauntlet: When a checkout has upsells configured, and a PayPal payment method is chosen, the maximum amount of the upsell guantlet is used when authorizing funds. By doing this, the checkout is able to offer upsells and capture funds without having the customer login to PayPal again. Some merchants have need to implement their own upsell gauntlet. To provide a custom gauntlet and accept PayPal, you will need to supply two additional fields in your CheckoutRequest object.
Your guantlet pages are responsible for loading up the cart again, displaying offers, adding them to the cart, and then doing another "checkout" call at the end of the guantlet. This will again submit the cart to the UltraCart checkout service, finalize the order, and present the customer with a receipt.
|
CheckoutResponse
This is the object returned from the REST API when the cart is submitted to be an order.
...
Field | Type | Comment | |||||||
labels | hash | this hash contains all the labels for the various fields below. This hash is powerful because it contains the mappings you specify in the back end "screen branding' section. See the order labels section for individual listings. | |||||||
merchantId | string | your merchant id | |||||||
customerProfileId | int | customer's internal identifier | |||||||
orderId | string | order id | |||||||
rejected | boolean | true if the order was rejected | |||||||
themeCode | string | the theme code applied to this order. See screen branding. This code is often used when creating buy links to apply the proper look and feel to an order page. Some merchants only have one theme. Some merchants have 50. | |||||||
creationDate | string | ISO-8601 format. When the order was created | |||||||
creationDateFormatted | string | DD-MMM-YYYY format. When the order was created | |||||||
shipOnDate | string | ISO-8601 format. When the order was requested to ship on. | |||||||
shipOnDateFormatted | string | DD-MMM-YYYY format. When the order was requested to ship on. | |||||||
saturdayDelivery | boolean | true if the order is set for Saturday delivery | |||||||
rejectedDate | string | ISO-8601 format. When the order was rejected (null if it hasn't been) | |||||||
rejectedDateFormatted | string | DD-MMM-YYYY format of when the order was rejected, if it was. | |||||||
quoteExpirationDate | string | ISO-8601 format. If this order is a quote, when the quote expires. | |||||||
quoteExpirationDateFormatted | string | DD-MMM-YYYY format. If this order is a quote, when the quote expires. | |||||||
status | string | Completed, Rejected, Quote Sent, Quote Requested, Pre-Order Item, Pending | |||||||
testOrder | boolean | true if this order was a test | |||||||
shippingMethod | string | a bare bones description of the shipping method | |||||||
shippingMethodName | string | a friendly version of the shipping method. This should be preferred for display over shippingMethod | |||||||
shippingMethodDetailed | string | an elaborate string contain shippingMethodName and any features such as lift gates and ship to residential, | |||||||
shippingMethodCompany | string | UPS, FedEx, etc. | |||||||
shipping3rdPartyAccountNumber | string | ||||||||
string | |||||||||
ccEmails | string[ ] | an array of email addresses who were cc'd on the order. | |||||||
giftEmail | string | the gift recipient's email address | |||||||
billToCompany | string | ||||||||
billToTitle | string | ||||||||
billToFirstName | string | ||||||||
billToLastName | string | ||||||||
billToAddress1 | string | ||||||||
billToAddress2 | string | ||||||||
billToCity | string | ||||||||
billToState | string | ||||||||
billToPostalCode | string | ||||||||
billToCountry | string | ||||||||
billToDayPhone | string | ||||||||
billToEveningPhone | string | ||||||||
shipToCompany | string | ||||||||
shipToTitle | string | ||||||||
shipToFirstName | string | ||||||||
shipToLastName | string | ||||||||
shipToAddress1 | string | ||||||||
shipToAddress2 | string | ||||||||
shipToCity | string | ||||||||
shipToState | string | ||||||||
shipToPostalCode | string | ||||||||
shipToCountry | string | ||||||||
shipToDayPhone | string | ||||||||
shipToEveningPhone | string | ||||||||
gift | boolean | true if the order is a gift | |||||||
liftGate | boolean | true if the order requires a lift gate to deliver. | |||||||
shipToResidential | boolean | true if the delivery is a residence | |||||||
hidePaymentInformation | boolean | whether or not to show payment information. Imagine the scenario where the cost is zero and/or gift certificates were used. | |||||||
refundPresent | boolean | duplicate of hasRefund. Use hasRefund, as this field is deprecated and will be removed without warning. | |||||||
taxShipping | boolean | is shipping taxed? this affects the display of subtotal information (tax before subtotal or subtotal before tax). | |||||||
taxCounty | string | ||||||||
referralCode | string | ||||||||
advertisingSource | string | ||||||||
paymentMethod | string | Credit Card, PayPal Order, etc. Supported payment methods as of 6/2013 (list may change):
| |||||||
paymentNote | string | A friendly working of the paymentMethod. For display purposes, use this value instead of paymentMethod. It will always read the same or better. | |||||||
cardType | string | The type of credit card used. VISA, MasterCard, etc. | |||||||
cardNumber | string | masked. last four digits. | |||||||
coupons | Coupon | The coupon class contains two simple fields: code and description | |||||||
items | Item[ ] | The items for this order | |||||||
giftWrapTitle | string | the name of the gift wrap | |||||||
giftWrapCost / giftWrapCostFormatted | number / string | ||||||||
hasDiscount | boolean | true if a discount was made somewhere (often useful for adding an extra table column, etc.) | |||||||
hasRefund | boolean | true if a refund was made somewhere (often useful for adding an extra table column, etc.) | |||||||
subtotalBeforeDiscount / subtotalBeforeDiscountFormatted | number / string | ||||||||
discount / discountFormatted | number / string | ||||||||
subtotal / subtotalFormatted | number / string | subtotal with any discounts and refunds already applied | |||||||
subtotalRefunded / subtotalRefundedFormatted | number / string | ||||||||
taxRate / taxRateFormatted | number / string | ||||||||
shippingHandlingDiscount / shippingHandlingDiscountFormatted | number / string | ||||||||
shippingHandlingTotal / shippingHandlingTotalFormatted | number / string | total with any discounts and refunds already applied. | |||||||
shippingHandlingRefunded / shippingHandlingRefundedFormatted | number / string | ||||||||
tax / taxFormatted | number / string | tax with any refund already applied | |||||||
taxRefunded / taxRefundedFormatted | number / string | ||||||||
giftCharge / giftChargeFormatted | number / string | ||||||||
surcharge / surchargeFormatted | number / string | showBuysafe | boolean | true if this order used buySAFE and the amounts should be shown. | buysafeCost / buysafeCostFormatted | number / string | buysafeRefunded / buysafeRefundedFormatted | number / string | |
boolean | true if this order used InsureShip and the amounts should be shown.
| ||||||||
number / string | insure ship cost | ||||||||
number / string | value of any insure ship refunded | ||||||||
total / totalFormatted | number / string | grand total | |||||||
totalRefunded / totalRefundedFormatted | number / string | of the total, this amount was refunded | |||||||
showCurrencyWarning | boolean | true if the currency warning (next line) should be shown. | |||||||
currencyWarning | string | this is the standard currency warning if the order was placed in a different currnency. It contains a nicely formatted message to show to the customer. | |||||||
giftCertificateCode | string | the gift certificate code. If the gift certificate was a credit card type, the code will be masked. | |||||||
giftCertificateAmount / giftCertificateAmountFormatted | number / string | the amount used of the gift certificate | |||||||
giftMessage | string[ ] | array of gift message lines when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired. | |||||||
specialInstructions | string[ ] | array of special instructions text when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired. | |||||||
comments | string[ ] | array of comments when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired. | |||||||
trackingNumbers | string[ ] | array of tracking numbers | |||||||
orderCase | Case | See the case object above. If there is a case (customer feedback) associated with this order, it will be populated in this value. |
...
Hash Key | Default | |
quoteRequestIdField | Quote Request ID | |
requestDateField | Request Date | |
expirationDateField | Quote Expiration Date | |
orderIdField | Order ID | |
sbtField | SBT | |
orderDateField | Order Date | |
billToHeader | Bill To | |
shipToHeader | Ship To | |
jobTitleField | Job Title | |
titleField | Title | |
nameField | Name | |
companyField | Company | |
addressField | Address | |
cityField | City | |
stateField | State | |
zipField | Zip | |
countryField | Country | |
emailField | ||
ccEmailField | CC Email | |
giftEmailField | Gift Email | |
giftField | Gift | |
phoneField | Phone | |
eveningPhoneField | Evening Phone | |
taxCountyField | Tax County | |
shippingMethodField | Shipping Method | |
residential | Residential | |
liftGate | Lift Gate | |
shipOnDateField | Ship on Date | |
deliveryDateField | Delivery Date | |
shipOnAccountField | Ship on Account | |
advertisingSourceField | Advertising Source | |
wrappingPaperField | Wrapping Paper | |
itemHeader | Item | |
quantityHeader | Quantity | |
descriptionHeader | Description | |
amountHeader | Amount | |
refundedHeader | Refunded | |
subtotalBeforeDiscountsField | Subtotal before discounts | |
discountsField | Discounts | |
subtotalField | Subtotal | |
shippingHandlingField | Shipping/Handling | |
taxRateField | Tax Rate | |
taxField | Tax | |
giftChargeField | Gift Charge | |
surchargeField | Surcharge | |
giftCertificateField | Gift Certificate | |
totalField | TotalbuySafeFree | Free! |
yourActualMessage | Your actual financial statement may vary due to actual currency conversion. |
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
function createCart() { jQuery.ajax({ url: '/rest/cart', headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantIdUltraCartMerchantID' dataType: 'json' }).done(function (cart) { jQuery('#createCartResults').html('<pre>' + JSON.stringify(cart, null, ' ') + '</pre>'); }); } jQuery(document).ready(function () { jQuery('#createCartButton').on('click', createCart); }); |
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
// since this demonstration has both a set and a clear, I'll need some state. // so I'm going to use a global variable to store a cart reference. Don't hate me. var finalizeCart = null; function finalizeAfter() { if (!finalizeCart) { jQuery.ajax({ url: '/rest/cart', headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantIdUltraCartMerchantID' dataType: 'json', async: false // for the demonstration, I'm keeping it simple with an synchronous call... }).done(function (cart) { finalizeCart = cart; }); } jQuery.ajax({ url: '/rest/cart/setFinalizeAfter?minutes=20', //minutes is optional. default is 30 type: 'POST', // Notice headers : { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', data: JSON.stringify(finalizeCart), dataType: 'json' }).done(function (data, textStatus, jqXHR) { var txt = jqXHR.status == 204 ? "Server returned 204 'No Content', so the setFinalizeAfter was successful" : "Error. setFinalizeAfter failed with this: " + textStatus; var pre = jQuery('<pre>'); pre.text(txt); jQuery('#finalizeResults').html('').append(pre); }); } function clearFinalizeAfter() { if (!finalizeCart) { alert('Please click the finalizeAfter button before attempting to clear it.'); return; } jQuery.ajax({ url: '/rest/cart/clearFinalizeAfter', type: 'POST', // Notice headers : { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', data: JSON.stringify(finalizeCart), dataType: 'json' }).done(function (data, textStatus, jqXHR) { var txt = jqXHR.status == 204 ? "Server returned 204 'No Content', so the clearFinalizeAfter was successful" : "Error. clearFinalizeAfter failed with this: " + textStatus; var pre = jQuery('<pre>'); pre.text(txt); jQuery('#finalizeResults').html('').append(pre); }); } jQuery(document).ready(function () { jQuery('#finalizeAfterButton').on('click', finalizeAfter); jQuery('#finalizeClearButton').on('click', clearFinalizeAfter); }); |
...
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
var customerCart = null; // another global variable. I need to keep state for this demonstration function register() { // any cart passed to register must have a valid merchant id AND cart id, so I'm creating a cart here. if (!customerCart) { jQuery.ajax({ url: '/rest/cart', headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantIdUltraCartMerchantID' dataType: 'json', async: false // for the demonstration, I'm keeping it simple with an synchronous call... }).done(function (cart) { customerCart = cart; }); } customerCart.email = jQuery.trim(jQuery('.customer-section input[name=email]').val()); customerCart.password = jQuery.trim(jQuery('.customer-section input[name=password]').val()); jQuery.ajax({ url: '/rest/cart/register', type: 'POST', // Notice headers : { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', data: JSON.stringify(customerCart), dataType: 'json' }).done(function (loggedInCart) { customerCart = loggedInCart; var txt = JSON.stringify(customerCart, null, ' '); var pre = jQuery('<pre>'); pre.text(txt); jQuery('#customerResults').html('').append(pre); }); } function logout() { if (!customerCart || !customerCart.loggedIn) { alert('Please login first.'); return; } jQuery.ajax({ url: '/rest/cart/logout', type: 'POST', // Notice headers : { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', data: JSON.stringify(customerCart), dataType: 'json' }).done(function (loggedOutCart) { customerCart = loggedOutCart; var txt = JSON.stringify(customerCart, null, ' '); var pre = jQuery('<pre>'); pre.text(txt); jQuery('#customerResults').html('').append(pre); }); } function login() { // any cart passed to register must have a valid merchant id AND cart id, so I'm creating a cart here. if (!customerCart) { alert('Please register first to create a cart'); return; } customerCart.email = jQuery.trim(jQuery('.customer-section input[name=email2]').val()); customerCart.password = jQuery.trim(jQuery('.customer-section input[name=password2]').val()); jQuery.ajax({ url: '/rest/cart/login', type: 'POST', // Notice headers : { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', data: JSON.stringify(customerCart), dataType: 'json' }).done(function (loggedInCart) { customerCart = loggedInCart; var txt = JSON.stringify(customerCart, null, ' '); var pre = jQuery('<pre>'); pre.text(txt); jQuery('#customerResults').html('').append(pre); }); } function resetPassword() { // any cart passed to register must have a valid merchant id AND cart id, so I'm creating a cart here. if (!customerCart) { alert('Please register first to create a cart'); return; } customerCart.email = jQuery.trim(jQuery('.customer-section input[name=email3]').val()); jQuery.ajax({ url: '/rest/cart/resetPassword', type: 'POST', // Notice headers : { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', data: JSON.stringify(customerCart), dataType: 'text' // Notice - plain text response. no json }).done(function (response) { var pre = jQuery('<pre>'); pre.text(response); jQuery('#customerResults').html('').append(pre); }); } jQuery(document).ready(function () { jQuery('#registerButton').on('click', register); jQuery('#logoutButton').on('click', logout); jQuery('#loginButton').on('click', login); jQuery('#resetPasswordButton').on('click', resetPassword); }); |
...