ISD Commerce - Intel® Commerce Services REST API Reference

Intel® Commerce Services REST API Reference

• Legal Information
• Table of Calls
• Reference Tables
  • Cart Structure
  • Commodity Codes
  • Locales and Locale Codes
  • Currency, Currency Codes, and Location Support
  • Payment Types, Payment Codes, and Maximum Amounts
  • Cart Status Codes
• Basic Commerce Calls
  • Post Cart
  • Delete Cart
  • Update Cart
  • Get Cart
  • Get Multiple Carts
  • Get Cart Status
  • Get Cart Tax
  • Put Cart Purchase
  • Post Cart Purchase
  • Get Order
  • Get Multiple Orders
  • Put Refund
  • Get Billing Profile
• Subscription Calls
  • Subscription Tables
    • Subscription Structure
    • Subscription Status Codes
  • Post Subscription
  • Put Subscription
  • Get Subscriptions
  • Put Subscription Refund
  • Cancel Subscription by ID
• Billing Profile Page
• Error Handling

 

This is the complete reference for Intel® Commerce Services REST Interface Version 1. This discussion assumes that you already have a basic understanding of Commerce Services REST APIs. If not, see the Intel Commerce Services REST Developer's Guide.

The following list provides basic information to help implement Commerce Services API calls:

• The term user in this document refers to the consumer, the person using the app to perform a commerce activity such as making a purchase.
• All developers must have an Intel® Identity Services account established and a commerce store established. See the Intel Commerce Services REST Developer's Guide for more information on this.
• Calls to execute purchases require the user to have an Intel Identity Services account and to have given permission to the app to access their information.
• Your app must place the access token for Commerce calls in the HTTP header (or in the URI) prior to executing each call. The descriptions below assume that authorization is already complete and that the app already has a valid access token.
• Commerce Services returns response status for each call in JSON (JavaScript* Object Notation) format only.
• Data transferred between apps and Commerce Services data structures (for example, cartStructure) is performed in JSON format.
• Some of the cart calls support limited anonymous browsing sessions by end-users . Anonymous browsing means one of the following:
  • The user does not have an Intel Identity account.
  • The user has not yet given permission to share their information with Commerce Services.
  • The application has not provided the user's information.
  
  Anonymous use allows users to create carts and add items to the cart or remove them (but not purchase carts), without sharing their identities with the app.
• The URL for REST calls is the same for apps that are being developed and have been released (except when testing commerce transactions).
• A testing path with a base URL of https://api.intel.com/test-commerce/v1/ is provided so you can test commerce transactions without incurring actual credit card charges.
• You will also need to create test user accounts that use test credit cards to test commerce transactions. These test accounts are actually full Intel Identity Services accounts, but with a separate URL to manage test users. This separate URL is https://test-commerce.intel.com/profile/paymentmethods2.aspx. Consult your Intel representative for information on creating these accounts.

Note: Because tokens are long, in API calls we usually substitute {access_token} or {refresh_token} for the real tokens. For calls that include elements like client ID, client secret, and user ID, we usually substitute {client_id}, {client_secret}, and {userid} for the real elements. In some cases, like initial use, we may show the real token or element. An example access token is shown below:

2/gAAAAB-gK_mJ8IW5-PQX8LkMkHXAl4viM0vRppECIkBVmfR1SOeQgvhLQnQzrwWKnbbsW1AKBzKss6eD0H3p0HMtIwtbgFQpeiqf0hDUEQlXTbt4UpKphIcV95Gc0C3PtkgNboV1TLGCC_bu5gLFXQJGAhmB6lkcJ5UwHGyn8BxFoayTdAEAAIAAAACDjEGPraEwMdWDz5MHNkulggsPdX41i4dMrdVcQdSBOcAP9vt9n0GwVNnJljsSCOH4UNHjosPpm7iwcOfF_4i_4InxRa-jRC0RWJWMxk9Xl-Uhtdv9WlxMgNZeSrSt9ySKCtREeCxYEBI1qwrnAy4a4zZ5aXAevtiXx41T7IQGu3QV2oq_4etvssMPhokSYkRAhk_nSz9dcThH2u8w-NXZl3av-rS9eiGaVxQvqqmRG79F1iw-fu5frOirJSLEofvc9nlGGZOEMk53tC0siRuP8rJOqaBJsOuPWN5widmNlirKuMjkTVShAaw-j03zMS4L39P3iuY-d9zLZUpyP3zh9poaRGEUKU5UXayGZIk76HcSsZBriPjV_84prhbh93F83XkWSOcWk1uwU_5GLPP2vu0VRxTuU_G4d1a3-aIjxE0T_OuFVSY0Lw5aAH2urUCljxbU8XDhKaOG8fi1-_HwII-5v-zLit83yy3QbOEFQ

 

Table of Calls

The following table lists each call by its call group and summarizes the function of the call.

Commerce Services REST API Call Groups

CART
Call	Description
Post Cart	Create a new cart.
Delete Cart	Delete an existing cart.
Update Cart	Update contents of an existing cart.
Get Cart	Get the contents of an existing cart.
Get Multiple Carts	Get the contents of multiple existing carts.
Get Cart Status	Get the status of an existing cart.
Get Cart Tax	Determine taxes on contents of an existing cart.
ORDER
Call	Description
Put Cart Purchase	Put Cart Purchase submits an existing cart for purchase.
Post Cart Purchase	Post Cart Purchase creates a cart and submits it for purchase in a single call.
Get Order	Get details of an order.
Get Multiple Orders	Get details of multiple orders.
Put Refund	Submit a full or partial refund for a past order.
PROFILE
Call	Description
Get Billing Profile	Get relevant information related to user's commerce billing profile.
SUBSCRIPTION
Call	Description
Post Subscription	Creates a new subscription.
Put Subscription	Activates a subscription that was previously created.
Get Subscriptions	Gets information on specified subscriptions.
Put Subscription Refund	Refund a subscription or part of a subscription.
Cancel Subscription by ID	Cancels the specified subscription.

Reference Tables

Cart Structure

cartStructure is a structure used by many of the API calls. The following table lists the elements of cartStructure. Not every field appears in every JSON Request or Response. For example, orderId does not appear in Responses until a cart has been purchased. JSON Requests have fewer fields than JSON Responses. The minimum JSON Requests for a call are shown in the discussion for that call.

PARAMETERS	REQUIRED?	INPUT/OUTPUT	DESCRIPTION
actualPrice	Yes	Input	Actual price of item. Must be equal to or less than listPrice. VAT inclusive but US tax exclusive. See notes below for valid values.
billingCountry	No (Yes for Get Cart Tax and Put Cart Purchase)	Input	Billing country code. Follows ISO 3166-1 alpha-2 format.
cartId	Yes	Output Input	First returned when cart is created. Then used as input for other calls.
commodityCode	Yes	Input	Commodity code used to identify tax rate. These are predefined UNSPSC (United Nations Standard Products and Service Code) values that apps must use for proper taxation on transactions. See the Commodity Codes table for valid values and their meaning.
currencyType	Yes	Input	Currency of item prices in cart in ISO 4217 format. See Currency, Currency Codes, and Location Support table for valid values and their meaning.
date	No	Output	The date of the transaction in UTC. Follows RFC 3339 (ISO 8601) format.
extendedPrice	No	Output	quantity * actualPrice. VAT inclusive but US tax exclusive. See notes below for valid values.
externalProductCode	Yes	Input	Provided for developers to use for their own product codes. Maximum number of characters is 100.
id	Yes	Output (Input for refund)	Output: unique identifier for each cart line item. id is only required as Input for refund. Valid value: Integer greater than 0.
isTaxCalculated	No	Output	Boolean: 1=yes; 0=no.
lineItemTax	No	Output	Total tax associated with a given line item. See notes below for valid values.
listPrice	Yes	Input	List price of item. Must be equal to or greater than actualPrice. See notes below for valid values.
locale	Yes	Input	Locale of items / descriptions / email templates related to a given line item in RFC 5646 format. See Locale Codes and Locales table for valid values and their meaning.
name	Yes	Input	Line item name that you want to appear in invoices. Maximum number of characters is 100.
orderId	Yes	Output (Input for refund)	Returned when cart is purchased. Then used as input to get order information or for a refund (if needed).
orderTotal	No	Output	Sum of: extendedPrice of all id items + lineItemTax of all id items. See notes below for valid values. See Payment Types, Codes, and Maximum Amounts table below for payment types, codes, and maximum purchase limits.
paymentType	No	Output	The payment type that was used to either calculate the tax or make the purchase. Examples: a string such as "VISA" or "AMEX". May be an empty string. See Payment Types, Codes, and Maximum Amounts table below for payment types, codes, and maximum purchase limits.
paymentTypeId	No	Output Input	This is returned in some calls such as Update Cart or Get Cart Tax. Can be used by Put Cart Purchase. This number uniquely identifies the paymentType associated with the cart and is influenced by billingCountry and Currency. This is a more precise way to specify the method of payment than paymentType in cases where more than one card of the same paymentType exists (for example, two VISA cards).
quantity	Yes	Input	Quantity of item. Valid value is an integer greater than 0.
refundExtendedPrice	No	Output	Extended price for refund for a given line item. VAT inclusive but US tax exclusive. See notes below for valid values.
refundLineItemTax	No	Output	Refunded tax for a given line item. See notes below for valid values.
refundQuantity	Yes*	Input Output	Provided by developers and updated by commerce system. Required for partial refunds only and is returned to represent the quantity that was refunded. Valid value: Decimal number with 2 or fewer decimal places.
refundSubtotal	No	Output	Sum of refundExtendedPrice for all line items. See notes below for valid values.
refundTaxtotal	No	Output	Sum of refundLineItemTax from all line items. See notes below for valid values.
refundTotal	No	Output	Sum of: refundSubtotal + refundTaxTotal for non-VAT countries. For VAT countries, this is the sum of all refundSubtotal entries. See notes below for valid values.
status	No	Output	This code is returned to show the status of the cart. See Cart Status Codes for valid values and their meaning.
subtotal	No	Output	For non-VAT countries, sum of extendedPrice of all id items. For VAT countries, sum across all id items of (extendedPrice - lineItemTax). See notes below for valid values.
taxTotal	No	Output	Total of all taxes for all id items. See notes below for valid values.
taxType	No	Output	This code is returned in Get Cart, Get Carts. Get Order, Put/Post Cart Purchase, Get Cart Tax, and Put Refund to specify the tax type. Valid values are: "none", "vat", and "sales".
userId	No	Output	0=Anonymous; otherwise this is the userId of the user.

Notes

• Prices are decimal numbers with two or fewer decimal places.
• When using decimals, use a period as the decimal separator. Do not use a comma as the decimal separator.
• Responses from cartStructure REST API calls can contain values such as an empty string or the value zero based on factors such as: (1) whether a cart is associated with a user, (2) availability of a user's Billing Profile Information, and (3) whether taxes have been calculated.

Commodity Codes

PRODUCT TYPE	COMMODITY CODE
Software	4323.120
Video Rental	551115.400
eBook	551115
Electronic Publication	55111506.120
Video Sale	55111510.120
Music	55111512.100
Data Service	811120
Business Use Application Service	81112106.100
Service	81112201.420

Locales and Locale Codes

LOCALE/LANGUAGE	LOCALE CODE	NOTES
Danish	da
Dutch	nl
English	en
Finnish	fi
French	fr
German	de
Italian	it
Japanese	ja
Korean	ko
Norwegian	nb	Also maps "no" to Norwegian
Polish	pl
Portuguese	pt
Russian	ru
Simplified Chinese	zh-HANS	Also maps all combinations starting with "zh" to Simplified Chinese, except those listed below for Traditional Chinese.
Spanish	es
Swedish	sv
Traditional Chinese	zh-HANT	Also maps the following to Traditional Chinese: "zh-ht", "zh-mo", "zh-tw", and zh-CHT

Currency, Currency Codes, and Currency-to-Location Support

CURRENCY	CURRENCY CODE	SUPPORTED LOCATIONS	SUPPORTED PAYMENT TYPES
Brazilian Real	BRL	Brazil	MSCD, VISA, PAYPAL
Canadian Dollar	CAD	Canada	AMEX, MSCD, VISA, PAYPAL
EURO	EUR	Aland Islands, Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Israel, Italy, Latvia, Lithuania, Luxembourg, Malta , Netherlands, Norway, Poland, Portugal, Romania, Serbia (not PayPal), Slovakia, Slovenia, Spain, Sweden, Switzerland, South Africa, Turkey, United Arab Emirates, Venezuela	MSCD, VISA, PAYPAL
Great Britain Pound	GBP	Guernsey, Isle of Man, Jersey, United Kingdom	MSCD, VISA, PAYPAL
Japanese Yen	JPY	Japan	AMEX, MSCD, VISA, PAYPAL
Mexican Peso	MXN	Mexico	MSCD, VISA, PAYPAL
Russian Ruble	RUB	Russia	MSCD, VISA
United States Dollar	USD	Argentina, Chile, Colombia, Costa Rica, Ecuador, United States, Australia, Hong Kong, India, Indonesia, Malaysia, New Zealand, Philippines, Singapore, South Korea, Taiwan, Thailand	AMEX, MSCD, VISA, PAYPAL

Payment Types, Payment Codes, and Maximum Amounts

PAYMENT TYPE	TYPE CODE	MAXIMUM PURCHASE AMOUNT
American Express*	AMEX	Maximum amount must be less than $50,000 USD.
Carte Bleue*	CARTEBLEUE-SSL	Maximum amount must be less than $50,000 USD.
Cartes Bancaires*	CB-SSL	Maximum amount must be less than $50,000 USD.
MasterCard*	MSCD	Maximum amount must be less than $50,000 USD.
VISA*	VISA	Maximum amount must be less than $50,000 USD.
PayPal*	PAYPAL	Maximum amount must be less than $10,000 USD, £550 GBP, €8000.

Cart Status Codes

STATUS	DESCRIPTION
pending	Cart has been created and may be modified.
awaiting_web_confirmation	A web confirmation is in the process of being shown to the user or has been shown. Awaiting confirmation result to process the cart.
awaiting_sms_confirmation	An SMS confirmation is in the process of being sent to the user or has been sent. Awaiting confirmation result to process the cart.
deleted	Cart was deleted.
processing_payment	The purchase process has been initiated and the cart is in the process of being processed.
processing_refund	The refund process has been initiated and the order is in the process of being refunded.
order_completed	Order was completed.
error_payment_system	During a purchase attempt, an error occurred not related to the user's payment information, such as tax systems being down, payment processor being down, or a Commerce Services system error.
error_invalid_payment_details	The user's payment information was invalid during a purchase. Possible cause are an expired credit card, canceled credit card, credit card that was refused to be processed, or payment information that was invalidated by an administrator.
error_refund_invalid_payment_details	The user's payment information was invalid during a refund. Possible causes are an expired credit card, canceled credit card, credit card that was refused to be processed, or payment information that was invalidated by an administrator.
error_refund_system	During a refund attempt, an error occurred not related to the user's payment information, such as tax systems being down, payment processor being down, or a Commerce Services system error.
partially_refunded	Partial order was refunded.
refunded	Order was refunded.

Example JSON cartStructure showing US Tax

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "PP14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.09,"extendedPrice": 1.99,"refundQuantity": 0.5,"refundLineItemTax": 0.05,"refundExtendedPrice": 1.00
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "PP13","quantity": 2,"actualPrice": 2.49,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.22,"extendedPrice": 4.98,"refundQuantity": 2,"refundLineItemTax": 0.22,"refundExtendedPrice": 4.98
    }
],"cartId": "f776fd54-e171-42d6-a4ab-2dbf5d376db2","orderId": "f776fd54-e171-42d6-a4ab-2dbf5d376db2","userId": "6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025","currencyType": "USD","locale": "en","subtotal": 6.97,"isTaxCalculated": 1,"orderTotal": 7.28,"taxTotal": 0.31,"refundSubtotal": 5.98,"refundTaxTotal": 0.27,"refundTotal": 6.25,"billingCountry": "US","paymentType": "VISA","paymentTypeId": 4,"date": "2012-06-26T05:49:36Z","taxType": "sales","status": "partially_refunded"
}     

Example JSON cartStructure showing VAT

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "PP14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.33,"extendedPrice": 1.99,"refundQuantity": 0.5,"refundLineItemTax": 0.17,"refundExtendedPrice": 1.00
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "PP13","quantity": 2,"actualPrice": 2.49,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.83,"extendedPrice": 4.98,"refundQuantity": 2,"refundLineItemTax": 0.83,"refundExtendedPrice": 4.98
    }
],"cartId": "f776fd54-e171-42d6-a4ab-2dbf5d376db2","orderId": "f776fd54-e171-42d6-a4ab-2dbf5d376db2","userId": "6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025","currencyType": "EUR","locale": "en","subtotal": 5.81,"isTaxCalculated": 1,"orderTotal": 6.97,"taxTotal": 1.16,"refundSubtotal": 4.98,"refundTaxTotal": 1.00,"refundTotal": 5.98,"billingCountry": "DE","paymentType": "VISA","paymentTypeId": 4,"date": "2012-06-26T05:49:36Z""taxType": "vat","status": "partially_refunded"
}
}

Basic Commerce Calls

Post Cart

The base URL for all calls in this document points to the Commerce Services Test path (test-commerce in the path). You need to change your base URL (that is, remove the test- element from the path) when moving to the released stage.

Creates a new shopping cart using the information in {cartStructure}. For application authorization, the call returns a shopping cart ID that supports anonymous creation of shopping carts. For user authorization, the call uses a user ID from Intel Identity Services, which returns a shopping cart ID that enables purchases to be made.

The following is the application authorization HTTP method, including the access token in the HTTP header:

Method	POST
URL Structure	https://api.intel.com/test-commerce/v1/carts
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below)

The following is the user authorization HTTP method, including the user ID from Intel Identity Services in the URI and the access token in the HTTP header:

Method	POST
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}/carts
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below)

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
cartstructure	Yes	Request body	See cartStructure description earlier in this document for details.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".
userid	No	URI	User identity from Intel Identity Services. The user's identity is only available if the user gives the application access to user information.

Example Usage

Application authorization call:

Method	POST
URL	https://api.intel.com/test-commerce/v1/carts
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below)

User authorization call with user ID from Intel Identity Services:

Method	POST
URL	https://api.intel.com/test-commerce/v1/users/02cb74de-4401-4f54-beee-577cd09134a1/carts
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below)

JSON Request

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99

    },
    {
        "id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99
    }
],"currencyType": "USD","locale": "en","billingCountry": "US"
}
}

Response Codes

HTTP Error/Code	Service Error Code	Message	Description
201	N/A	Operation successful. Cart was created successfully.	Cart ID is returned. Location Header in response returns location of cart. Example: https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10001	Invalid Request: Prices must be positive values, contain only 2 or fewer decimal places. When using decimals, use a period as the decimal separator not a comma	The Price is not formatted correctly, such as actualPrice: 0.999.
400	CMR-10002	Invalid Request: Cart structure or refund structure is wrong.	The cart or refund structure is incorrect, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10004	Invalid Request: Invalid billing country or unsupported billing country.	Occurs when the billing country syntax is invalid, such as 11, or the billing country is unsupported.
400	CMR-10008	Invalid Request: The store is not configured.	Occurs if your store is not present in the system or it is not configured for currencies, countries, and/or payment methods.
400	CMR-10009	Invalid Request: Either the store is not configured or there exists an invalid value for billing country or currency or locale type.	May be generated by invalid data or if the store not present in the system. The store must also be configured for currencies, countries, and payment methods.
404	CMR-10015	Not Found: The commodity code is invalid.	The commodity code is not one of the approved commodity codes.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10021	Conflict: Maximum order total is reached.	The total is equal to or greater than 50,000.01 USD or 41,000.01 EUR or 32,000.01 GBP.
409	CMR-10022	Conflict: The maximum number of line items is reached.	The number of line items exceeds the 100 line item limit.
409	CMR-10024	Conflict: The maximum length of the line item is exceeded.	The line item name exceeds the 100 character limit.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

JSON Response

{"cartId": "6d1d2aa9-0059-4f64-93d8-894ea74800cf"
}       

Notes

• Once a cart is assigned to a user, it cannot be reassigned to another user or unassigned.
• If a user is assigned to a cart during this call, and no country or payment method are associated with the cart, then a country and payment method are automatically assigned based on the currency for the cart and the user's preferred payment method. (If the user's preferred payment method does not match the currency for the cart, then the store's preferred payment method is used.)
• Subsequent calls to access the cart append the cartId to the URI as shown in the following Get Cart call:

Method	GET
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Delete Cart

Deletes the specified shopping cart. This operation requires that the application include the access token in the HTTP header and the cartid of the shopping cart that's going to be deleted in the URI:

Method	DELETE
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
cartid	Yes	URI	Unique identifier for the shopping cart to be deleted.
accept	Yes	Request header	Value must be "application/json".

Example Usage

Method	DELETE
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
204	N/A	Operation successful.	The specified cart was deleted.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	The store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Possible causes: The cart/order does not exist. The app does not have access to the cart/order. The cart is already deleted.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Possible causes: Cart is ordered then a delete request is submitted before the delete request is done. Cart is ordered then an update request is submitted before the order is done.

Note: Carts with a purchase currently in process cannot be deleted.

Update Cart

Updates the shopping cart specified by {cartid}, using the information in {cartStructure}. For application authorization, the call updates a shopping cart during an anonymous browsing session. For user authorization, the call includes the user ID from Intel Identity Services, which updates a shopping cart that enables purchases.

Application authorization call includes access token in the HTTP header and the cart ID in the URI:

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below)

User authorization call includes access token in the HTTP header and both the user ID from Intel Identity Services and the cart ID in the URI:

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/{userid}/carts/{cartid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below)

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
cartstructure	Yes	Request body	See cart structure earlier in this section for details.
cartid	Yes	URI	Unique identifier for the shopping cart to be updated.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".
userid	No	URI	User's identity from Intel Identity Services. For the user's identity to be available, the user must authorize access to their information.

Example Usage

Application authorization call:

Method	PUT
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below)

User authorization call with the user ID from Intel Identity Services:

Method	PUT
URL	https://api.intel.com/test-commerce/v1/users/02cb74de-4401-4f54-beee-577cd09134a1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below)

JSON Request

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99

    },
    {
        "id": 2,"name": "Some Name 3","externalProductCode": "P15","quantity": 1,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99
    }
],"currencyType": "USD","locale": "en","billingCountry": "US"
}
}

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful. Cart was updated successfully.	Cart ID is returned. Location Header in response returns location of cart. Example: https://api.intel.com/test-commerce/v1/carts/12345678-1234-1234-1234-123456789ABC
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10001	Invalid Request: Prices must be positive values, contain only 2 or fewer decimal places. When using decimals, use a period as the decimal separator not a comma.	The Price is not formatted correctly, such as actualPrice: 0.999.
400	CMR-10002	Invalid Request: Cart structure or refund structure is wrong.	The cart or refund structure is incorrect, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10004	Invalid Request: Invalid billing country or unsupported billing country.	Occurs when the billing country syntax is invalid, such as 11, or the billing country is unsupported.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10009	Invalid Request: Either the store is not configured or there exists an invalid value for billing country or currency or locale type.	May be generated by invalid data or by the store not being present in the system. The store must also be configured for currencies, countries, and payment methods.
404	CMR-10015	Not Found: The commodity code is invalid.	The commodity code is not one of the approved commodity codes.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10021	Conflict: Maximum order total is reached.	The order total exceeds 50,000 USD (that is, the total is equal to or greater than 50,000.01 USD or 41,000.01 EUR or 32,000.01 GBP).
409	CMR-10022	Conflict: The maximum number of line items is reached.	The number of line items exceeds the 100 line item limit.
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted.
409	CMR-10024	Conflict: The maximum length of the line item is exceeded.	The line item name exceeds the 100 character limit.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

JSON Response

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    },
    {"id": 2,"name": "Some Name 3","externalProductCode": "P15","quantity": 1,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    }
],"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "0","currencyType": "USD","locale": "en","isTaxCalculated": 0,"billingCountry": "US","paymentType": "","paymentTypeId": 0,"date": "2013-08-07T23:50:58Z","status": "pending","subtotal": 3.98,"orderTotal": 3.98,"taxTotal": 0,"refundSubtotal": 0,"refundTaxTotal": 0,"refundTotal": 0,"taxType": "none"
}
}

Notes

• The userId value has a value of 0 until a cart is assigned to a user.
• Once a cart is assigned to a user, it cannot be reassigned to another user, or unassigned.
• If a user is assigned to a cart during this call, and no country or payment method are associated with the cart, then a country and payment method are automatically assigned based on the currency for the cart and the user's preferred payment method. (If the user's preferred payment method does not match the currency for the cart, then your store's preferred payment method is used.)

Get Cart

Get contents of the specified cart. If a cart has already been put into purchase, this call returns the contents of the order associated with cartid.

The application must include the access token in the HTTP header and the cart ID for the cart in the URI:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
cartid	Yes	URI	Unique identifier for the shopping cart you are requesting contents for.
accept	Yes	Request header	Value must be "application/json".

Example Usage

Method	GET
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	The structure for the specified cart was returned. See below for example.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10007	Invalid Request: Date format is invalid.	The date format is not valid or the start date is before the minimum start date of 20120101. (Format is YYYYMMDD.)
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-30310	Invalid Request: Status is not recognized.	The status of the cart is not a valid value.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 3.98
    }
],"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "0","currencyType": "USD","locale": "en","isTaxCalculated": 0,"billingCountry": "US","paymentType": "","paymentTypeId": 0,"date": "2013-08-07T23:50:58Z","status": "pending","subtotal": 5.97,"orderTotal": 5.97,"taxTotal": 0,"refundSubtotal": 0,"refundTaxTotal": 0,"refundTotal": 0,"taxType": "none"
}
}

Note: The userId value will be 0 until a cart is assigned to a user.

Get Multiple Carts

Gets all the carts or carts for the specified user. This call enables filtering by dates and/or cart status. This call also enables results to be paged. For application authorization, the call returns shopping cart information regardless of user. For user authorization, the call includes a user ID from Intel Identity Services, which allows information to be gathered for a specific user's carts.

Application authorization call, including the access token in the HTTP header and the date range and paging parameters:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/carts?start_date={YYYYMMDD}&end_date={YYYYMMDD}&$limit={limit}&$offset={offset}&status={status}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

This is a user authorization call that includes the access token in the HTTP header and the user ID from Intel Identity Services and the date range, paging parameters, and status in the URI:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}/carts?start_date={YYYYMMDD}&end_date={YYYYMMDD}&$limit={limit}&$offset={offset}&status={status}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
start_date	Yes	URI	Start date for cart information request in UTC format. Minimum start date is 20120101 (2012, January 1).
end_date	Yes	URI	End date for cart information request in UTC format. End date must be greater than or equal to the start date.
$limit	No	URI	Specifies the maximum number of carts to be returned in a page of results. Integer between 0 and 1,000; default if not specified is 500.
$offset	No	URI	Specifies the page number to include in the results from the total available pages. Integer greater than 0; default if not specified is 0.
status	No	URI	Cart status. See Cart Status table for valid values. Only valid when userid is also used.
accept	Yes	Request header	Value must be "application/json".
userid	No	URI	User's identity from Intel Identity Services. The user must authorize the application to use their information for the user's identity to be available.

Example Usage

Application authorization call with start and end dates:

Method	GET
URL	https://api.intel.com/test-commerce/v1/carts?start_date=20120801&end_date=20120831
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

User authorization call with user ID from Intel Identity Services, start and end dates, and carts with completed orders:

Method	GET
URL	https://api.intel.com/test-commerce/v1/users/02cb74de-4401-4f54-beee-577cd09134a1/carts?start_date=20120901&end_date=20120930&status=order_completed
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Application authorization call with start and end dates, and $limit of 50 carts per result with $offset of page 0 (first page):

Method	GET
URL	https://api.intel.com/test-commerce/v1/carts?start_date=20130701&end_date=20130731&$limit=50&$offset=0
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	JSON format is returned: cartid, date, status, total price, currency type, URI for each cart in the format https://api.intel.com/test-commerce/v1/carts/{cartid}
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10007	Invalid Request: Date format is invalid.	The date format is not valid or the start date is before the minimum start date of 20120101. (Format is YYYYMMDD.)
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10018	Invalid Request: The value of the $limit or $offset is incorrect.	Note that $limit must be an integer between 0 and 1,000. $offset must be an inter greater than 0.
400	CMR-30310	Invalid Request: Status is not recognized.	The status of the cart is not a valid value.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

{"data": {"currentItemCount": 2,"totalItems": 2,"itemsPerPage": 500,"startIndex": 0,"nextLink": "https://api.intel.com/test-commerce/v1/users/6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025/carts?start_date=20130730&end_date=20130807","previousLink": "https://api.intel.com/test-commerce/v1/users/6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025/carts?start_date=20130730&end_date=20130807&$offset=0&$limit=500","pagingLinkTemplate": "https://api.intel.com/test-commerce/v1/users/6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025/carts?start_date={start_date}&end_date={end_date}&$offset={offset}&$limit={limit}","kind": "carts","items": [
    {"cartId": "507009e3-4336-43a5-9dbb-4547f24f2ff6","userId": "6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025","currencyType": "USD","date": "2013-07-30T01:24:02Z","status": "pending","cartUrl": "https://api.intel.com/test-commerce/v1/carts/507009e3-4336-43a5-9dbb-4547f24f2ff6","totalPrice": 5.97
    },
    {"cartId": "0cc3839d-1291-4f6d-bcf7-aaad862b8354","userId": "6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025","currencyType": "USD","date": "2013-07-30T01:01:47Z","status": "pending","cartUrl": "https://api.intel.com/test-commerce/v1/carts/0cc3839d-1291-4f6d-bcf7-aaad862b8354","totalPrice": 5.97
    }
]
}
}          

Get Cart Status

Get status for the specified cart. The application must include the access token in the HTTP header and the cart ID for the shopping cart in the URI:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}/status
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
cartid	Yes	URI	Unique identifier for the shopping cart you are requesting status for.
accept	Yes	Request header	Value must be "application/json".

Example Usage

Method	GET
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf/status
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	The status for the specified cart was returned. See below for example.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
404	CMR-10016	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart does not exist, (2) Cart is ordered then a delete request is submitted while order is in progress. (3) Cart is ordered then an update request is submitted while order is in progress.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

js
{"cartStatus": "awaiting_web_confirmation"
}

Note: See supported Cart Status Codes.

Get Cart Tax

Calculate tax for the specified cart. This call calculates VAT tax for EEC countries or US tax for the United States. The application must include the access token in the HTTP header and the cart ID for the shopping cart in the URI. Payment type can optionally be included in the URI through paymenttype or paymenttypeid.

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}/tax?paymenttype={paymenttype}&paymenttypeid={paymenttypeid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Note: See the notes below for processing rules.

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
cartid	Yes	URI	Unique identifier for the shopping cart you are requesting tax information for.
accept	Yes	Request header	Value must be "application/json".
paymenttype	No	URI	Payment type to use for the tax calculation, such as "VISA". See Payment Types, Payment Codes, and Maximum Amounts for valid values.
paymenttypeid	No	URI	Payment Type id to use for the tax calculation. Payment Type Id represents a combination of data including the Billing Country, Currency, and Payment Type and is a number generated by Commerce Services in response to Update Cart and Get Cart Tax. This is a more precise way to specify the method of payment than paymentType in cases where more than one card of the same paymentType exists (for example, two VISA cards).

Example Usage

Method	GET
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf/tax?paymenttype=VISA
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	Cart returned with tax information included.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-30610	Invalid Request: The payment type is not supported.	The format of the payment type is invalid or the payment type is not supported.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.12,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.24,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 3.98
    }
],"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","isTaxCalculated": 1,"billingCountry": "US","paymentType": "VISA","paymentTypeId": 2,"date": "2013-08-07T23:50:58Z","status": "pending","subtotal": 5.97,"orderTotal": 6.33,"taxTotal": 0.36,"refundSubtotal": 0,"refundTaxTotal": 0,"refundTotal": 0,"taxType": "sales"
}
}  

Notes

• Using paymenttypeid is the recommended method of specifying the payment method.
• If paymenttypeid and paymenttype are both included in the query string, paymenttypeid takes precedence and paymenttype is ignored.
• If paymenttype is included in the query string, the billing information associated with paymenttype is used for calculating the tax.
• If paymenttype is not included in the query string, the consumer's preferred payment method is used, assuming it is supported by your Commerce Services store.
• If the user information or the payment information associated with the user is missing from the system, the call returns an error.
• The userId value will be 0 until a cart is assigned to a user.

Put Cart Purchase

Put Cart Purchase submits an existing cart (already assigned to a user) to the payment processor. Carts that are successfully purchased become orders.

Note: Put Cart Purchase requires a cart that's already assigned to a user (user authorization access token) and valid payment information.

A basic version of this call uses the billing profile in cartStructure. An alternate version of the call uses the paymenttype or paymenttypeid in the query string.

billingCountry is used to specify a billing profile if billingCountry is present in the cartStructure.

Here is the basic version, with the access token in the HTTP header and the cart ID in the URI (using billing profile in cartStructure):

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}/purchase
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	n/a

Here is the alternate version, with the access token in the HTTP header and the cart ID and payment type or payment type ID associated with the user's Billing Profile in the URI:

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/carts/{cartid}/purchase?paymenttype={paymenttype}&paymenttypeid={paymenttypeid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token must be a user authorization access token.
cartid	Yes	URI	Unique identifier for the shopping cart you are submitting for purchase.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".
paymenttype	No	URI	Payment type to use for the tax calculation, such as "VISA". See Payment Types, Payment Codes, and Maximum Amounts for valid values.
paymenttypeid	No	URI	Payment Type Id represents a combination of data including the Billing Country, Currency, and Payment Type and is a number generated by Commerce Services in response to Update Cart and Get Cart Tax. This is a more precise way to specify the method of payment than paymentType in cases where more than one card of the same paymentType exists (for example, two VISA cards).

Example Usages

Basic version of the call (using billing profile in cartStructure):

Method	PUT
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf/purchase
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	n/a

Alternate version of the call using payment type ID associated with the user's Intel Identity Services profile:

Method	PUT
URL	https://api.intel.com/test-commerce/v1/carts/6d1d2aa9-0059-4f64-93d8-894ea74800cf/purchase?paymenttypeid=7
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	n/a

JSON Request for Put Cart Purchase

(not applicable for this call)

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	Order was already purchased. cartStructure is returned with current status, taxes, etc.
201	N/A	Operation successful.	Order was created. Updated cartStructure is returned with current status, taxes, etc.
202	N/A	Operation successful.	Confirmation is necessary. Provide URL, SMS instructions and code number, or SMS message stating the confirmation is being sent to phone. cartStructure is not returned at this time. (Updated cartStructure is returned after purchase successfully completes.)
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10004	Invalid Request: Invalid billing country or unsupported billing country.	Occurs when the billing country syntax is invalid, such as 11, or the billing country is unsupported.
400	CMR-30610	Invalid Request: The payment type is not supported.	The format of the payment type is invalid or the payment type is not supported by the Commerce Services or by this store.
400	CMR-30615	Invalid Request: The token is either missing or invalid.	Application authorization is required. The access token must include 'profile:basic' access rights.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10021	Conflict: Maximum order total is reached.	The order total exceeds 50,000 USD (that is, the total is equal to or greater than 50,000.01 USD or 41,000.01 EUR or 32,000.01 GBP).
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted.
409	CMR-10024	Conflict: The maximum length of the line item is exceeded.	The line item name exceeds the 100 character limit.
409	CMR-30650	Conflict: Minimum purchase price is not reached.	The purchase price is below the supported minimum price.
409	CMR-30652	Conflict: The order total will be denied on the test systems.	The total of your order matches the card processor value for denials on the test systems.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

Sample JSON Response for Return Codes 200, 201

  {"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.12,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.24,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 3.98
    }
    ],"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","orderId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","isTaxCalculated": 1,"billingCountry": "US","paymentType": "VISA","paymentTypeId": 2,"date": "2013-08-08T00:19:59Z","status": "order_completed","subtotal": 5.97,"orderTotal": 6.33,"taxTotal": 0.36,"refundSubtotal": 0,"refundTaxTotal": 0,"refundTotal": 0,"taxType": "sales"
    }
}       

Notes

• Using paymenttypeid is the recommended method of specifying the payment method.
• If this payment type is different than the payment type used for the prior Get Cart Tax call, the tax is recalculated using the current payment type before processing.

Post Cart Purchase

Post Cart Purchase creates a cart from cartStructure, assigns it to a user, and submits it to the payment processor. Carts that are successfully purchased become orders.

Post Cart Purchase uses the current cartStructure and specified user ID and submits the cart for purchase. (It creates the cart, assigns it to a user, and submits it for purchase in a single call.) An alternate version of the call uses the paymenttype or paymenttypeid in the query string.

billingCountry is used to specify a billing profile if billingCountry is present in the cartStructure.

Basic version, with the access token in the HTTP header and using billing profile in cartStructure:

Method	POST
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}/purchase
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	(see JSON Request below)

Alternate version, with the access token in the HTTP header and payment type or payment type ID associated with the user's Billing Profile in the URI:

Method	POST
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}/purchase?paymenttype={paymenttype}&paymenttypeid={paymenttypeid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	(see JSON Request below)

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token must be a user authorization access token.
userid	Yes	URI	User's identity from Intel Identity Services. The user must give the application access to their information for the user's identity to be available.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".
paymenttype	No	URI	Payment type to use for the tax calculation, such as "VISA". See Payment Types, Payment Codes, and Maximum Amounts for valid values.
paymenttypeid	No	URI	Payment Type Id represents a combination of data including the Billing Country, Currency, and Payment Type and is a number generated by Commerce Services in response to Update Cart and Get Cart Tax. This is a more precise way to specify the method of payment than paymentType in cases where more than one card of the same paymentType exists (for example, two VISA cards).
cartStructure	Yes	Request body	Post Cart Purchase requires a valid cartStructure in the body.

Example Usages

Single call purchase:

Method	POST
URL	https://api.intel.com/test-commerce/v1/carts/users/{userid}/purchase?paymenttypeid=7
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	(see JSON Request below)

JSON Request for Post Cart Purchase

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99

    },
    {
        "id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99
    }
],"currencyType": "USD","locale": "en","billingCountry": "US"
}
}

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	Order was already purchased. cartStructure is returned with current status, taxes, etc.
201	N/A	Operation successful.	Order was created. Updated cartStructure is returned with current status, taxes, etc.
202	N/A	Operation successful.	Confirmation is necessary. Provide URL, SMS instructions and code number, or SMS message stating the confirmation is being sent to phone. cartStructure is not returned at this time. (Updated cartStructure is returned after purchase successfully completes.)
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10004	Invalid Request: Invalid billing country or unsupported billing country.	Occurs when the billing country syntax is invalid, such as 11, or the billing country is unsupported.
400	CMR-30610	Invalid Request: The payment type is not supported.	The format of the payment type is invalid or the payment type is not supported by the Commerce Services or by this store.
400	CMR-30615	Invalid Request: The token is either missing or invalid.	Application authorization is required. The access token must include 'profile:basic' access rights.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10021	Conflict: Maximum order total is reached.	The order total exceeds 50,000 USD (that is, the total is equal to or greater than 50,000.01 USD or 41,000.01 EUR or 32,000.01 GBP).
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted.
409	CMR-10024	Conflict: The maximum length of the line item is exceeded.	The line item name exceeds the 100 character limit.
409	CMR-30650	Conflict: Minimum purchase price is not reached.	The purchase price is below the supported minimum price.
409	CMR-30652	Conflict: The order total will be denied on the test systems.	The total of your order matches the card processor value for denials on the test systems.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

Sample JSON Response for Return Codes 200, 201

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.12,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.24,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 3.98
    }
],"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","orderId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","isTaxCalculated": 1,"billingCountry": "US","paymentType": "VISA","paymentTypeId": 2,"date": "2013-08-08T00:19:59Z","status": "order_completed","subtotal": 5.97,"orderTotal": 6.33,"taxTotal": 0.36,"refundSubtotal": 0,"refundTaxTotal": 0,"refundTotal": 0,"taxType": "sales"
}
}       

Notes

• Using paymenttypeid is the recommended method of specifying the payment method.
• If this payment type is different than the payment type used for the prior Get Cart Tax call, the tax is recalculated using the current payment type before processing.

Get Order

Get order information after purchase to obtain order history. Returns an instance of {cartStructure} for the specified {orderid}. Can be used to present details of order to the consumer.

The application must include the access token in the HTTP header and the order ID for the desired order in the URI:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/orders/{orderid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
orderid	Yes	URI	Unique identifier for the order you are requesting information on. (This is the same identifier as cart iD used to make the purchase.)
accept	Yes	Request header	Value must be "application/json".

Example Usage

Method	GET
URL	https://api.intel.com/test-commerce/v1/orders/6d1d2aa9-0059-4f64-93d8-894ea74800cf
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	(see JSON Request below)

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	Order details are returned in cartStructure.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Not found. The order ID does not exist or is invalid. This can occur when: (1) An order does not exist, or (2) The application does not have access to an order.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "P14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.12,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 1.99
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "P13","quantity": 2,"actualPrice": 1.99,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.24,"refundQuantity": 0,"refundLineItemTax": 0,"refundExtendedPrice": 0,"extendedPrice": 3.98
    }
],"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","orderId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","isTaxCalculated": 1,"billingCountry": "US","paymentType": "VISA","paymentTypeId": 2,"date": "2013-08-08T00:19:59Z","status": "order_completed","subtotal": 5.97,"orderTotal": 6.33,"taxTotal": 0.36,"refundSubtotal": 0,"refundTaxTotal": 0,"refundTotal": 0,"taxType": "sales"
}
}       

Get Multiple Orders

Get a list of orders, where each entry in the list represents an order and includes ordernumber, date, status, total price, currency type, and the URL for each order. This call is used after a purchase to obtain order history. This call gets all the orders or orders for the specified user. This call enables filtering by dates allows results to be paged.

For application authorization, the call returns order information for all orders in the date range. For user authorization, the call includes a user ID from Intel Identity Services, which allows order history to be returned for a specific user.

This is an application authorization call, with the access token in the HTTP header and paging parameters in the URI:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/orders?start_date={YYYYMMDD}&end_date={YYYYMMDD}&$limit={limit}&$offset={offset}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

This is a user authorization call, with the access token in the HTTP header, the user ID from Intel Identity Services, and the date range and paging parameters in the URI:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}/orders?start_date={YYYYMMDD}&end_date={YYYYMMDD}&$limit={limit}&$offset={offset}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
start_date	Yes	URI	Start date for order information request in UTC format. Minimum start date is 20120101 (2012, January 1).
end_date	Yes	URI	End date for order information request in UTC format. End date must be greater than or equal to the start date.
$limit	No	URI	Specifies the maximum number of orders to be returned in a page of results. Integer between 0 and 1,000; default if not specified is 500.
$offset	No	URI	Specifies the page number to include in the results from the total available pages. Integer greater than 0; default if not specified is 0.
accept	Yes	Request header	Value must be "application/json".
userid	No	URI	User's identity from Intel Identity Services. The user must give the application access to their information for the user's identity to be available.

Example Usage

This is an application authorization call with start and end dates:

Method	GET
URL	https://api.intel.com/test-commerce/v1/orders?start_date=20120801&end_date=20120831
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

This is a user authorization call with user ID from Intel Identity Services and start and end dates:

Method	GET
URL	https://api.intel.com/test-commerce/v1/users/{userid}/orders?start_date=20120901&end_date=20120830
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

This is an application authorization call with start and end dates, and a $limit of 50 orders per result with an $offset of page zero (first page):

Method	GET
URL	https://api.intel.com/test-commerce/v1/orders?start_date=20120801&end_date=20120831&$limit=50&$offset=0
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	JSON format is returned: order ID, date, status, total price, currency type, URI for each cart in the format https://api.intel.com/test-commerce/v1/orders/{orderid}
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10007	Invalid Request: Date format is invalid.	The date format is not valid or the start date is before the minimum start date of 20120101. (Format is YYYYMMDD.)
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10018	Invalid Request: The value of the $limit or $offset is incorrect.	Note that $limit must be an integer between 0 and 1,000. $offset must be an inter greater than 0.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

{"data": {"currentItemCount": 3,"totalItems": 3,"itemsPerPage": 500,"startIndex": 0,"nextLink": "https://api.intel.com/test-commerce/v1/users/23147cd5-6e47-46e4-8e93-59780b5bc15c/orders?start_date=20120701&end_date=20130807","previousLink": "https://api.intel.com/test-commerce/v1/users/23147cd5-6e47-46e4-8e93-59780b5bc15c/orders?start_date=20120701&end_date=20130807&$offset=0&$limit=500","pagingLinkTemplate": "https://api.intel.com/test-commerce/v1/users/23147cd5-6e47-46e4-8e93-59780b5bc15c/orders?start_date={start_date}&end_date={end_date}&$offset={offset}&$limit={limit}","kind": "orders","items": [
    {"cartId": "cf2bb891-1da0-473f-a01c-10cca01073ad","orderId": "cf2bb891-1da0-473f-a01c-10cca01073ad","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","date": "2013-08-08T00:19:59Z","status": "order_completed","orderUrl": "https://api.intel.com/test-commerce/v1/orders/cf2bb891-1da0-473f-a01c-10cca01073ad","totalPrice": 6.33
    },
    {"cartId": "6fc0c94a-5f77-4d39-aa8b-27df7e2418f5","orderId": "6fc0c94a-5f77-4d39-aa8b-27df7e2418f5","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","date": "2013-08-07T18:02:59Z","status": "order_completed","orderUrl": "https://api.intel.com/test-commerce/v1/orders/6fc0c94a-5f77-4d39-aa8b-27df7e2418f5","totalPrice": 5.29
    },
    {"cartId": "11b14285-8d90-498c-b9f0-706250bc6aca","orderId": "11b14285-8d90-498c-b9f0-706250bc6aca","userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","date": "2013-08-07T17:50:36Z","status": "order_completed","orderUrl": "https://api.intel.com/test-commerce/v1/orders/11b14285-8d90-498c-b9f0-706250bc6aca","totalPrice": 19.37
    }
]
}
}

Put Refund

Requests a full or partial refund on an order. This call is useful for developer Management CSubscription Callsonsole applications. The call to refund a full order must include the access token in the HTTP header, the order ID for the order to be refunded, and the path to /refundfullorder in the URI. No additional information is needed.

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/orders/{orderid}/refundfullorder
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	n/a

The call to refund a partial order must include the access token in the HTTP header, the order ID for the order to be refunded, and the path to /refundpartialorder in the URI. The JSON request must include the refundLines object:

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/orders/{orderid}/refundpartialorder
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below)

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
orderid	Yes	URI	Unique identifier for the order you are requesting a refund on. (This is the same value as the original cart ID.)
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".
refundline	No	Request body	This parameter is required for partial refunds. For partial refunds, refundline must contain a list of id and refundquantity. This parameter should not be included for full refunds.

Example Usage

The following call refunds a full order:

Method	PUT
URL	https://api.intel.com/test-commerce/v1/orders/6d1d2aa9-0059-4f64-93d8-894ea74800cf/refundfullorder
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	n/a

The following call refunds a partial order:

Method	PUT
URL	https://api.intel.com/test-commerce/v1/orders/6d1d2aa9-0059-4f64-93d8-894ea74800cf/refundpartialorder
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below)

JSON Request Containing refundLines Object for Partial Refund

js
{"data": {"kind": "refundLines","items": [
    {"id": 1,"refundQuantity": 0.5
    },
    {"id": 2,"refundQuantity": 2
    }
]
}
}

See cartStructure for definition and values for refundQuantity.

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	Order was already refunded. This return value is not supported for partial refunds.
201	N/A	Operation successful.	Refund was processed.
202	N/A	Operation successful.	Confirmation is necessary. Provide URL. Cart structure is not returned in this case.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10002	Invalid Request: Cart structure or refund structure is wrong.	The cart or refund structure is incorrect, but there is no additional information to specify the cause of the error.
400	CMR-60011	Invalid Request: Order line item is not valid.	Order line item is not found.
400	CMR-60012	Invalid Request: Invalid refund request.	Order line refund amount is more than the amount that can be refunded.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Not found. The orderid does not exist or is invalid. This can occur when: (1) an order does not exist, or (2) the application does not have access to an order.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted.
409	CMR-60061	Conflict: Request of a refund past the date allowed for refunding.	Orders have a limited number of days where a refund can be requested. The request for a refund is past the limit.
409	CMR-60062	Conflict: Request of a refund before the order has finished processing.	Purchases must completely process before a refund can be requested. Typical processing time is between 1 hour and 24 hours.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

JSON Response

js
{"data": {"kind": "cartLine","items": [
    {"id": 1,"name": "Some Name 1","externalProductCode": "PP14","quantity": 1,"actualPrice": 1.99,"commodityCode": "4323.120","listPrice": 1.99,"lineItemTax": 0.09,"extendedPrice": 1.99,"refundQuantity": 0.5,"refundLineItemTax": 0.05,"refundExtendedPrice": 1.00
    },
    {"id": 2,"name": "Some Name 2","externalProductCode": "PP13","quantity": 2,"actualPrice": 2.49,"commodityCode": "551115.400","listPrice": 2.99,"lineItemTax": 0.22,"extendedPrice": 4.98,"refundQuantity": 2,"refundLineItemTax": 0.22,"refundExtendedPrice": 4.98
    }
],"cartId": "6d1d2aa9-0059-4f64-93d8-894ea74800cf","orderId": "6d1d2aa9-0059-4f64-93d8-894ea74800cf","userId": "6a8eb2ad-e8d4-4ac7-aa27-9246bca9a025","currencyType": "USD","locale": "en","subtotal": 6.97,"isTaxCalculated": 1,"orderTotal": 7.28,"taxTotal": 0.31,"refundSubtotal": 5.98,"refundTaxTotal": 0.27,"refundTotal": 6.25,"billingCountry": "US","paymentType": "VISA","paymentTypeId": 4,"date": "2012-06-26T05:49:36Z","taxType": "sales","status": "partially_refunded"
}
}

Get Billing Profile

Get the billing profile associated with the specified user from Commerce Services.This call only returns those payment methods enabled in your store.

The application must include the access token in the HTTP header and the user ID from Intel Identity Services in the URI.

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session.
userid	Yes	URI	User's identity from Intel Identity Services. The user must give the application access to their information for the user's identity to be available.
accept	Yes	Request header	Value must be "application/json".

Example Usage

Method	GET
URL	https://api.intel.com/test-commerce/v1/users/02cb74de-4401-4f54-beee-577cd09134a1
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	User's billing profile is returned with BillingCountry, BillingCurrency, PaymentType, and ConfirmationType.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

JSON Response

{"data": {"kind": "billingProfiles","items": [
    {"billingCountry": "US","billingCurrency": "USD","paymentType": "VISA","paymentTypeId": 5,"confirmationType": "cfm_typ_none","preferredPayment": 1
    },
    {"billingCountry": "DE","billingCurrency": "EUR","paymentType": "MSCD","paymentTypeId": 11,"confirmationType": "cfm_typ_none","preferredPayment": 0
    }
]
}
}

Billing Profile Response

The Billing Profile Response is returned by the Get Billing Profile call. The following table lists the elements of this response.

PARAMETERS	Description
billingCountry	Billing country code. Follows ISO 3166-1 alpha-2 format.
billingCurrency	Currency to use for billing in ISO 4217 format. See Currency, Currency Codes, and Location Support table above.
paymentType	Payment type to use for calculating the tax or making the purchase. Examples: a string such as "VISA" or "AMEX". May be an empty string.
paymentTypeId	This number uniquely identifies a payment method. This is a more precise way to specify the method of payment than paymentType in cases where more than one card of the same paymentType exists (for example, two VISA cards).
confirmationTypeId	Reserved for future use.
preferredPayment	Boolean: 1=this payment type is the preferred type; 0=this payment type is not the preferred payment type. (For Billing Profiles with more than one payment type included, only one can be the preferred payment type.)

Subscription Calls

Subscription Status Codes

Subscription Tables

Subscription Structure

subscriptionStructure is a structure used in JSON Requests and Responses for subscription calls. The following table lists the elements of subscriptionStructure. Not every field appears in every JSON Request or Response. (Many of the fields have identical counterparts as cartStructure).

PARAMETERS	REQUIRED?	INPUT/OUTPUT	DESCRIPTION
subscriptionId	No	Output Input	First returned when a subscription is created. Then used as input for many other subscription calls.
billingPeriod	Yes	Input/Output	This code specifies the billing period. Valid values are: "monthly" or "annual".
billingType	Yes	Input/Output	This code specifies the billing type. Valid values are: "prepay".
startDate	Yes	Input/Output	This code specifies the starting date for the subscription. Valid values are dates after equal to or later than the current date when the call is made. Valid format is UTC (YYYYMMDD) and "Immediate". Dates follow RFC 3339 (ISO 8601) format. If "Immediate", then the subscription starts now and the user must pay immediately.
maxNumberPeriods	Yes	Input/Output	An integer greater than or equal to 1 that specifies the number of billingPeriods that the subscription is active. If -1 is specified as an input, the subscription will be active continuously until canceled. For continuous subscriptions, this field will be blank in JSON output. Must be less than 2,147,483,647.
lastBilledDate	No	Output	The date on which the subscription was last billed. Valid format is UTC (YYYYMMDD).
lastBilledPeriod	No	Output	The billing period on which the subscription was last billed; same as the total number of billing periods to date.
nextBillingDate	No	Output	The next date that the subscription is billed.
storeId	No	Output	The ID of the store associated with the subscription.
attemptFailures	No	Output	The number of failed billing attempts for the subscription.
status	No	Output	The current status of the subscription. See Subscription Status Codes for valid values and their meaning.
productName	Yes	Input/Output	Line item name to appear in invoices for a subscription. Maximum number of characters is 100.
productCode	Yes	Input/Output	Provided for developers to use for their own product codes for a subscription. Maximum number of characters is 100.
commodityCode	Yes	Input	Commodity code used to identify tax rate. These are predefined UNSPSC (United Nations Standard Products and Service Code) values that apps must use for proper taxation on transactions. See the Commodity Codes table for supported codes and their meaning.
listPrice	Yes	Input/Output	List price of the subscription. Must be equal to or greater than actualPrice. See notes below for valid values.
actualPrice	Yes	Input/Output	Actual price of subscription. Must be equal to or less than listPrice. VAT inclusive but US tax exclusive. See notes below for valid values.
subtotal	No	Output	Sum of actualPrice of all subscriptionId items. See notes below for valid values.
taxTotal	No	Output	Total of all taxes for all subscriptionId items. See notes below for valid values.
orderTotal	No	Output	Sum of subtotal and taxTotal. See notes below for valid values. See Payment Types, Payment Codes, and Maximum Amounts table below for payment types, codes, and maximum purchase limits.
refundQuantity	No	Output	Quantity of subscriptions being refunded.
refundSubtotal	No	Output	Subtotal of the refund for the subscription.
refundTax	No	Output	Tax for refundSubtotal.
refundTotal	No	Output	Sum of refundSubtotal and refundTax. See notes below for valid values.
userId	No	Output	The userId of the user associated with the subscription.
currencyType	Yes	Input/Output	Currency of item prices in cart in ISO 4217 format. See Currency, Currency Codes, and Location Support table for valid codes and their meaning.
locale	Yes	Input/Output	Locale of subscriptions / descriptions / email templates related to a given subscription in RFC 5646 format. See Locale Codes and Locales table below.

Notes

• Prices are decimal numbers with two or fewer decimal places.
• When using decimals, use a period as the decimal separator not a comma.

Subscription Status Codes

Post Subscription

STATUS	DESCRIPTION
pending	Subscription has been created, but is not active yet.
active	Subscription is active.
billerror	An error occurred during when processing billing.
errordone	An error was detected on 3 sequential billing attempts. No more billing attempts will be made. (The Intel Commerce Services store administrator is notified when this occurs so they can pursue a resolution.)
done	Order was completed for the subscription.
deleted	Subscription was cancelled.

Example JSON subscriptionStructure

{"subscriptionId": "12345678-1234-1234-1234-123456789ABD","billingPeriod": "monthly","billingType": "prepay","startDate": "20130601","maxNumberPeriods": 12,"lastBilledDate": "20130801","nextBillingDate": "20131001","attemptFailures": 0,"status": "billerror","storeId": "eb02432d-6a90-68df-bceb-69590bbb171a","productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"userId": "6a9068df-eb02-432d-bceb-b171a69590bc","currencyType": "USD","locale": "en","refundQuantity": 0,"refundSubtotal": 0,"refundTax": 0,"refundTotal": 0
}

Post Subscription

Creates a new subscription in Commerce Services for the specified user. New subscriptions are created with a pending status and must be activated within 24 hours via a subsequent Put Subscription call.

The JSON request supports attributes to specify the start date and to define the subscription period or create a continuous subscription.

Method	POST
URL Structure	https://api.intel.com/test-commerce/v1/users/{userid}/subscriptions
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below)

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token must be a user authorization access token.
userid	Yes		The userId of the user associated with the subscription; from Intel Identity Services. The user must give the application access to their information for the user's identity to be available.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".
subscriptionStructure	Yes	Request body	This call requires a valid subscriptionStructure in the body.

Example Usage

Method	POST
URL	https://api.intel.com/test-commerce/v1/users/{userid}/subscriptions
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below)

JSON Request

One-year monthly subscription with future start date (assume call is made before December 1, 2013).

js
{"productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"billingPeriod": "monthly","startDate": "20131201","maxNumberPeriods": 12,"billingType": "prepay","currencyType": "USD","locale": "en"
}

One-year monthly subscription with immediate start date; billing date occurs monthly on same day as start day.

js
{"productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"billingPeriod": "monthly","startDate": "Immediate","maxNumberPeriods": 12,"billingType": "prepay","currencyType": "USD","locale": "en"
}

Response Codes

HTTP Code	Service Error Code	Message	Description
201	N/A	Operation successful.	Subscription was created. Updated subscriptionStructure is returned the JSON response.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10001	Invalid Request: Prices must be positive values, contain only 2 or fewer decimal places. When using decimals, use a period as the decimal separator not a comma.	The Price is not formatted correctly. For example, the actualPrice is 0.999.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10004	Invalid Request: Invalid billing country or unsupported billing country.	Occurs when the billing country syntax is invalid, such as 11, or the billing country is unsupported.
400	CMR-10005	Invalid Request: Currency type is invalid or unsupported.	The format of the currency type is invalid, such as USX, or the currency type is unsupported, such as CAD.
400	CMR-10006	Invalid Request: Locale is invalid or unsupported.	The format of the locale is invalid, such as "ex", or is unsupported, such as "he" (Hebrew).
400	CMR-10007	Invalid Request: Date format is invalid.	The date format is not valid or the start date is before the minimum start date of 20120101. (Format is YYYYMMDD.)
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10031	Invalid Request: Subscription structure or subscription refund structure is invalid.	The subscription / subscription refund structure is incorrect and a more detailed error cannot be provided.
400	CMR-10032	Invalid Request: Product name is missing or exceeds the maximum length.	The product name is mandatory and the limit is 100 characters.
400	CMR-10033	Invalid Request: Product code is missing or exceeds maximum length.	The product code is mandatory and the limit is 100 characters.
400	CMR-10034	Invalid Request: Billing period is invalid.	Billing period is invalid. Valid values are "monthly" or "yearly".
400	CMR-10035	Invalid Request: Start date format is invalid.	Valid dates must be later than today and in YYYYMMDD format or "immediate".
400	CMR-10036	Invalid Request: Maximum billing period is invalid.	The valid maximum number period is -1 or a positive integer number.
400	CMR-10037	Invalid Request: Billing type is invalid.	Billing type is invalid. The only valid type is "prepay".
404	CMR-10015	Not Found: The commodity code is invalid.	The commodity code is not one of the approved commodity codes.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10024	Conflict: The maximum length of the line item is exceeded.	The line item name exceeds the 100 character limit.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

Sample JSON Response

{"subscriptionId": "172e89c1-b0c0-4188-81e6-d3cea0dfb722","billingPeriod": "monthly","billingType": "prepay","startDate": "20131201","maxNumberPeriods": 12,"lastBilledDate": "","lastBilledPeriod": 0,"nextBillingDate": "20131201","attemptFailures": 0,"status": "pending","storeId": "H0jaWh3JiN6x9OpVD7Ydb52pvENHyjG6","productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"currencyType": "USD","locale": "en","subtotal": 1.99,"taxTotal": 0.12,"orderTotal": 2.11
}       

Note: Subscriptions that are not activated within 24 hours of being created are deleted from the Commerce Services system.

Put Subscription

Activates a subscription previously created using the Post Subscription call. This call must be executed within 24 hours to activate the subscription created by a previous Post call. Once activated, billing (that is, payment processing) occurs regularly based on the billing date for the subscription.

The start date and subscription period were previously defined by the JSON Request for the Post Subscription call.

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/subscriptions/{subscriptionid}/purchase
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token must be a user authorization access token.
subscriptionid	Yes	URI	Unique identifier for the subscription to be activated. The subscription ID is created via the Post Subscription call.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".

Example Usage

Method	PUT
URL	https://api.intel.com/test-commerce/v1/subscriptions/{subscriptionid}/purchase
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Scopes Already Granted	profile:basic, billing:confirm, user:scope, user:details
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	Subscription was already activated.
201	N/A	Operation successful.	Subscription was successfully activated. Updated subscriptionStructure is returned the JSON response.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-30615	Payment Information Required: Billing profile information is required to process the order.	User authorization is required. The access token must include the following access rights: 'profile:basic', 'billing:confirm', 'user:details', and 'user:scope'.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10038	Not Found: The subscription ID is invalid or the subscription was not found.	Either the subscription does not exist or the app does not have access to the subscription.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10021	Conflict: Maximum ordertotal is reached.	The order total exceeds 50,000 USD (that is, the total is equal to or greater than 50,000.01 USD or 41,000.01 EUR or 32,000.01 GBP).
409	CMR-10040	Conflict: Status of subscription prevents the requested action.	Occurs if the subscription is completed, deleted, or has an error status like: billerror or errordone.
409	CMR-10041	Conflict: Activation must occur with 24 hours of creation.	The requested activation is past the 24-hour time window since the original POST Subscription call.
409	CMR-30650	Conflict: Minimum purchase price is not reached.	The purchase price is below the supported minimum price.
409	CMR-30652	Conflict: The order total will be denied on the Test systems.	The order total matches the card processor's amount for denials on Test systems. (Some card processors define specific amounts for testing error logic; these amounts will generate errors during testing.)

Sample JSON Response

js
{"subscriptionId": "172e89c1-b0c0-4188-81e6-d3cea0dfb722","billingPeriod": "monthly","billingType": "prepay","startDate": "20131201","maxNumberPeriods": 12,"lastBilledDate": "","lastBilledPeriod": 0,"nextBillingDate": "20131201","attemptFailures": 0,"status": "active","storeId": "H0jaWh3JiN6x9OpVD7Ydb52pvENHyjG6","productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"currencyType": "USD","locale": "en","subtotal": 1.99,"taxTotal": 0.12,"orderTotal": 2.11,"refundQuantity": 0,"refundSubtotal": 0,"refundTax": 0,"refundTotal": 0
}

Notes

• Initial billing occurs based on the future date of startDate. If startDate is set to immediate, the billing occurs immediately upon activation.
• Billing for activated subscriptions occurs periodically based on the billingdate for the subscription.
• The payment for subscriptions uses the same payment processor used for the Put/Post Cart Purchase calls.
• Subscriptions that are not activated within 24 hours of being created are deleted from the Commerce Services system.

Get Subscriptions

Gets information on the subscriptions specified in the call. Subscriptions can be queried based on billing date, the start and end date, a specific user, a specific status, or for a combination of attributes. This call enables results to be paged.

Two versions of the call are supported. The first version specifies a specific billing date:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/subscriptions/billingdate/{YYYYMMDD}?$limit={limit}&$offset={offset}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

The second version of the call specifies start_date and end_date with an optional userId:

Method	GET
URL Structure	https://api.intel.com/test-commerce/v1/users/{userId}/subscriptions?start_date={YYYYMMDD}&end_date={YYYYMMDD}&status={status}$limit={limit}&$offset={offset}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token can be an authorization or user authorization access token.
*Must contain either billingdate or start_date/end_date but not both.
billingdate	*Yes	URI	Specifies the billing date to query on. Date must be in UTC format. The response includes a list of all subscriptions billed or to be billed on that date.
userid	No	URI	The userId of the user associated with the subscription(s); from Intel Identity Services. The user must give the application access to their information for the user's identity to be available.
start_date	*Yes	URI	Specifies the starting date for a date range. Date must be in UTC format. Earliest allowed date is January 1, 2012. Subscriptions created, to be billed, or were actually billed within the date range will be included in the response.
end_date	*Yes	URI	Specifies the ending date for a date range. Date must be in UTC format. Subscriptions created, billed, or to be billed within the date range are included in the response.
status	No	URI	Specifies the status of the subscriptions to be included in the query. Can be used to further limit the subscriptions returned in the response.
$limit	No	URI	Specifies the maximum number of subscriptions to be returned in a page of results. Integer between 0 and 1,000; if not specified, the default is 500.
$offset	No	URI	Specifies the page number to include in the results from the total available pages. Integer greater than 0; if not specified, the default is 0.
accept	Yes	Request header	Value must be "application/json".

Example Usage

Specifies a billing date:

Method	GET
URL	https://api.intel.com/test-commerce/v1/subscriptions/billingdate/20130716
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Specifies the start date, end date, status, page size, and page offset:

Method	GET
URL	https://api.intel.com/test-commerce/v1/subscriptions?start_date=20130601&end_date=20130831&status=active$limit=30&$offset=3
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
200	N/A	Operation successful.	The structure for the specified subscription was returned. See below for example.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10007	Invalid Request: Date format is invalid.	The date format is not valid or the start date is before the minimum start date of 20120101. (Format is YYYYMMDD.)
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10018	Invalid Request: The value of the $limit or $offset is incorrect.	Check the values of $limit and $offset and correct them.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

Sample JSON Response

{"data": {"currentItemCount": 3,"totalItems": 3,"itemsPerPage": 500,"startIndex": 0,"nextLink": "https://api.intel.com/test-commerce/v1/users/23147cd5-6e47-46e4-8e93-59780b5bc15c/subscriptions?start_date=20130601&end_date=20130808&_=1375973748929","previousLink": "https://api.intel.com/test-commerce/v1/users/23147cd5-6e47-46e4-8e93-59780b5bc15c/subscriptions?start_date=20130601&end_date=20130808&status=&$limit=500&$offset=0","pagingLinkTemplate": "https://api.intel.com/test-commerce/v1/users/23147cd5-6e47-46e4-8e93-59780b5bc15c/subscriptions?start_date={start_date}&end_date={end_date}&status={status}&$limit={limit}&$offset={offset}","kind": "subscriptions","items": [
    {"subscriptionId": "172e89c1-b0c0-4188-81e6-d3cea0dfb722","billingPeriod": "monthly","billingType": "prepay","startDate": "20131201","maxNumberPeriods": 12,"lastBilledDate": "","lastBilledPeriod": 0,"nextBillingDate": "","attemptFailures": 0,"status": "deleted","storeId": "H0jaWh3JiN6x9OpVD7Ydb52pvENHyjG6","productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","refundQuantity": 0,"refundSubtotal": 0,"refundTax": 0,"refundTotal": 0
    },
    {"subscriptionId": "afe95886-9fd8-461c-b79b-ee9c3ff82488","billingPeriod": "monthly","billingType": "prepay","startDate": "20131101","maxNumberPeriods": 12,"lastBilledDate": "","lastBilledPeriod": 0,"nextBillingDate": "20131101","attemptFailures": 0,"status": "active","storeId": "H0jaWh3JiN6x9OpVD7Ydb52pvENHyjG6","productName": "Saurabh's World Music Monthly","productCode": "MAG-SB0141","commodityCode": "4323.120","listPrice": 3.99,"actualPrice": 2.99,"userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","refundQuantity": 0,"refundSubtotal": 0,"refundTax": 0,"refundTotal": 0
    },
    {"subscriptionId": "dcba8081-da9e-4080-afd3-76c5783ed68c","billingPeriod": "monthly","billingType": "prepay","startDate": "20131201","maxNumberPeriods": 12,"lastBilledDate": "","lastBilledPeriod": 0,"nextBillingDate": "20131201","attemptFailures": 0,"status": "active","storeId": "H0jaWh3JiN6x9OpVD7Ydb52pvENHyjG6","productName": "Dan Barry's Recipes","productCode": "MAG-DB0235","commodityCode": "4323.120","listPrice": 2.99,"actualPrice": 1.99,"userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","refundQuantity": 0,"refundSubtotal": 0,"refundTax": 0,"refundTotal": 0
    }
]
}
}       

Put Subscription Refund

Refunds the specified subscription or part of the subscription.

Method	PUT
URL Structure	https://api.intel.com/test-commerce/v1/subscriptions/{subscriptionid}/refund
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept} Content-Type: {contenttype}
Body	(see JSON Request below for refund quantity)

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token can be an application or user authorization access token.
subscriptionid	Yes	URI	Unique identifier for the subscription to process a refund against.
accept	Yes	Request header	Value must be "application/json".
contenttype	Yes	Request header	Value must be "application/json".

Example Usage

Method	PUT
URL	https://api.intel.com/test-commerce/v1/subscriptions/{subscriptionid}/refund
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json Content-Type: application/json
Body	(see JSON Request below for refund quantity)

JSON Request

{"refundQuantity": 0.5
}

Response Codes

HTTP Code	Service Error Code	Message	Description
201	N/A	Operation successful.	Refund was successfully applied. subscriptionStructure is returned with response.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10002	Invalid Request: Cart structure or refund structure is wrong.	The cart or refund structure is incorrect, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-60012	Invalid Request: Invalid refund request.	Order line refund amount is more than amount remaining which can be refunded.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order.
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-60061	Conflict: Request of a refund past the date allowed for refunding.	Orders have a limited number of days where a refund can be requested. The request for a refund is past this date.
409	CMR-60062	Conflict: Request of a refund before the order has finished processing.	Purchases must completely process before a refund can be requested. Typical wait time before a refund can be requested is between 1 hour and 24 hours.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

Sample JSON Response

{"subscriptionId": "7b9021b7-73d7-42c1-aa90-0e79abaddf31","billingPeriod": "monthly","billingType": "prepay","startDate": "20130808","maxNumberPeriods": 12,"lastBilledDate": "20130808","lastBilledPeriod": 1,"nextBillingDate": "20130908","attemptFailures": 0,"status": "active","storeId": "H0jaWh3JiN6x9OpVD7Ydb52pvENHyjG6","productName": "Environment Vista Monthly","productCode": "MAG-114","commodityCode": "4323.120","listPrice": 1.99,"actualPrice": 0.99,"userId": "23147cd5-6e47-46e4-8e93-59780b5bc15c","currencyType": "USD","locale": "en","refundQuantity": 0.5,"refundSubtotal": 0.5,"refundTax": 0.03,"refundTotal": 0.53
}       

Cancel Subscription by ID

Cancels the subscription specified by the subscription ID:

Method	DELETE
URL Structure	https://api.intel.com/test-commerce/v1/subscriptions/{subscriptionid}
Headers	Key Value Authorization: Bearer {access_token} Accept: {accept}
Body	n/a

Input Parameters

PARAMETERS	Required?	Input Type	Description
access_token	Yes	Request header	Unique access token for the current session. For this call, the access token can be an application or user authorization access token.
subscriptionid	Yes	URI	Unique identifier for the subscription to be cancelled.
accept	Yes	Request header	Value must be "application/json".

Example Usage

Method	DELETE
URL	https://api.intel.com/test-commerce/v1/subscriptions/{subscriptionid}
Headers	Key Value Authorization: Bearer {access_token} Accept: application/json
Body	n/a

Response Codes

HTTP Code	Service Error Code	Message	Description
204	N/A	Operation successful.	Subscription was successfully deleted.
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
404	CMR-10038	Not Found: The product code is invalid or the subscription with the given product code was not found.	Either the product code does not exist or developer does not have access to this subscription with the given product code.
404	CMR-10039	Not Found: The subscription id is invalid or the subscription was not found.	Either the subscription does not exist or the app does not have access to the subscription.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.

Billing Profile Page

Users must set up a billing profile in Commerce Services before making purchases. Commerce Services accesses this profile as needed to calculate taxes, complete a purchase, or process a refund.

When an app detects that no billing profile exists, the app can forward the user to a Commerce Services page to create their billing profile. The Billing Profile page screens allow users to add payment methods. The base URIs for Billing Profile pages for testing vs. production use are as follows:

Testing URI:

https://test-commerce.intel.com/profile/billingprofile.aspx?apikey={client_id}&cartid={cartid}

 

Production URI:

https://commerce.intel.com/profile/billingprofile.aspx?apikey={client_id}&cartid={cartid}

 

You must include your client_id in the URL as the value for apikey. Some basic information is already filled in from the user's Intel Identity Services account, after they approve sharing of their information with the Billing Profile page. The user must complete the remaining Billing Profile's required fields and include at least one payment method.

Note: Developers must ensure through their own testing that the Success, Fail, and Callback URLs associated with the Billing Profile page are working URLs. Commerce Services does not validate these links. All callback URLs in the call must be fully qualified and start with http:// or https://.

Example using parameters:

https://test-commerce.intel.com/profile/billingprofile.aspx?apikey=8e9df53c-d28f-11e1-bd04-0050568c00f9&cartid={cartid}&success_url=https://testapp.greatapps.com/intelbilling/success.aspx&locale=en&error_url=https://testapp.greatapps.com/intelbilling/error.aspx&locale=en&code&error&callback_function=https://testapp.greatapps.com/intelbilling/callfunction.aspx&locale=en

 

Example success:

https://test-commerce.intel.com/profile/error.aspx?code=200&message=

 

Example fail:

https://test-commerce.intel.com/profile/error.aspx?code=CMR-80014&message=Locale+is+unsupported+or+invalid

 

Example using a non-English locale:

https://test-commerce.intel.com/profile/billingprofile.aspx?apikey=8e9df53c-d28f-11e1-bd04-0050568c00f9&cartid={cartid}&success_url=https://testapp.greatapps.com/intelbilling/success.aspx&locale:de&error_url=https://testapp.greatapps.com/intelbilling/error.aspx&locale:de&code&error&callback_function=https://testapp.greatapps.com/intelbilling/callfunction.aspx&locale=de

Input Parameters

PARAMETERS	Required?	Input Type	Description
apikey	Yes	URI	The unique client_id for the app. (Your Commerce Services store is associated with this client_id.)
successurl	No	URI	Redirect URL if payment was successfully authorized.
errorurl	No	URI	Redirect URL if the payment was not successfully authorized.
locale	No	URI	Browser locale is the default if this parameter is not passed. "en" is the default if the browser does not pass a locale. See the Locales and Locale Codes table for supported locales.
callbackurl	No	URI	Callback URL to redirect the user prior to using the Success or Error URLs above.
cartid	No	URI	When Cart ID is included, the Billing Profile Page lists the names and prices of the items in the cart in addition to the user's billing profile information.

Output Parameters

PARAMETERS	Description
errorcode	CMR-{unique_error_code}, where {unique_error_code} is a unique error code. See Error Codes below.
errormessage	A very brief description of the code meaning. See the Response Codes table below.

Response Codes

Error Code	Message	Description
CMR-80000	GENERIC_ERROR	Unexpected error during Billing Profile access.
CMR-80001	INVALID_USER	Invalid user ID.
CMR-80003	INVALID_PROFILE_ID	Invalid profile ID.
CMR-80004	INVALID_PAYMENT_TYPE	Invalid payment type.
CMR-80005	INVALID_EXPIRATION_DATE	Invalid expiration date.
CMR-80006	INVALID_USER_PAYMENT_METHOD	Invalid user payment method.
CMR-80007	INVALID_COUNTRY_CODE	Invalid country code or not valid strings (non-existent Country Code).
CMR-80008	INVALID_MERCHANT_ID	Invalid merchant ID.
CMR-80009	INVALID_ARGUMENTS	Invalid arguments.
CMR-80010	INVALID_DATE_TIME	Invalid transaction date time.
CMR-80011	BILLING_PROFILE_NOT_FOUND	The Billing Profile not found.
CMR-80012	INVALID_API_KEY	Your APIKey (client ID) is not provided or is invalid.
CMR-80013	STORE_NOT_FOUND	There is no store associated with the APIKey.
CMR-80014	INVALID_LOCALE	The locale is unsupported or invalid.
CMR-80015	PAYMENT_PROCESSING_ERROR	There was an error with the billing information at the payment processor.
CMR-80016	PAYMENT_PROCESSING_ERROR	There was a problem at the payment processor.
CMR-80017	INVALID_DATA	Legal restrictions prevent us from fulfilling the request.
CMR-80018	GENERIC_ERROR	General Commerce Services error.
CMR-80019	PAYMENT_PROCESSING_ERROR	There was a problem at the payment processor as this transaction was determined to be a high fraud risk.

Note: The Billing Profile page with no cart item contents is displayed by default when the Cart ID is not present or is incorrect, or when the cart is associated with a different user than the current user.

Error Handling

When errors are detected during an API call, an HTTP error is returned with detailed error information in the body of the JSON response. The following example shows one possible error message for HTTP Error 400:

{"error" : {"code": "CMR-10023","message": "Conflict: Status of cart/order prevents the requested action.","requestId": "c962fe29-d4e8-11e1-bd04-0050568c00f9"
}
}

Commerce Services error messages start with a CMR- prefix. If you see a different prefix, or no prefix, the error was returned by other services, such as Intel Identity Services.

Commerce Services REST Error Messages

HTTP Error/Code	Service Error Code	Message	Description
400	CMR-10000	Invalid Request: Generic Error	An error occurred, but there is no additional information to specify the cause of the error.
400	CMR-10001	Invalid Request: Prices must be positive values, contain only 2 or fewer decimal places. When using decimals, use a period as the decimal separator not a comma.	The Price is not formatted correctly, such as actualPrice: 0.999.
400	CMR-10002	Invalid Request: Cart structure or refund structure is wrong.	The cart or refund structure is incorrect, but there is no additional information to specify the cause of the error.
400	CMR-10003	Invalid Request: User ID is invalid.	The format of the user ID is invalid.
400	CMR-10004	Invalid Request: Invalid billing country or unsupported billing country.	Occurs when the billing country syntax is invalid, (for example, 11) or the billing country is unsupported.
400	CMR-10005	Invalid Request: Currency type is invalid or unsupported.	The format of the currency type is invalid, such as USX (instead of USD), or when the currency is not supported. See Currency, Currency Codes, and Location Support table for valid values and their meaning.
400	CMR-10006	Invalid Request: Locale is invalid or unsupported.	The format of the locale is invalid, such as ex, or is unsupported, such as he (Hebrew).
400	CMR-10007	Invalid Request: Date format is invalid.	The date format is not valid or the start date is before the minimum start date of 20120101. (Format is YYYYMMDD.)
400	CMR-10008	Invalid Request: The store is not configured.	Your store must be present in the system to execute this operation and be configured for currencies, countries, and payment methods.
400	CMR-10009	Invalid Request: Either the store is not configured or there exists an invalid value for billing country or currency or locale type.	May be generated by invalid data or by the store not being present in the system. The store must also be configured for currencies, countries, and payment methods.
400	CMR-10018	Invalid Request: The value of the $limit or $offset is incorrect.	Check the values of $limit and $offset and correct them.
400	CMR-10031	Invalid Request: Subscription structure or subscription refund structure is invalid.	The subscription / subscription refund structure is incorrect and a more detailed error cannot be provided.
400	CMR-10032	Invalid Request: Product name is missing, invalid, or exceeds the maximum length.	The product name is mandatory and the limit is 100 characters. The product name cannot contain the symbols < or >.
400	CMR-10033	Invalid Request: Product code is missing, invalid, or exceeds maximum length.	The product code is mandatory and the limit is 100 characters.The product name cannot contain the symbols < or >.
400	CMR-10034	Invalid Request: Billing period is invalid.	Billing period is invalid. It must be monthly or yearly.
400	CMR-10035	Invalid Request: Start date format is invalid.	Valid dates must be later than today and in YYYYMMDD format or immediate.
400	CMR-10036	Invalid Request: Maximum billing period is invalid.	The valid maximum number period is -1 or a positive integer number.
400	CMR-10037	Invalid Request: Billing type is invalid.	Billing type is invalid and currently accepts only prepay.
400	CMR-30310	Invalid Request: Status is not recognized.	The status of the cart is not a valid value.
400	CMR-30610	Invalid Request: The payment type is not supported.	The format of the payment type is invalid or the payment type is not supported.
400	CMR-30615	Invalid Request: The token is either missing or invalid.	Application authorization is required. The access token must include profile:basic access rights.
400	CMR-60011	Invalid Request: Order line item is not valid.	Order line item is not found.
400	CMR-60012	Invalid Request: Invalid refund request.	Order line refund amount is more than amount remaining that can be refunded.
402	CMR-10010	Payment Information Required: Billing profile information is required to process the order.	The billing information is invalid or insufficient to process the order.
404	CMR-10015	Not Found: The commodity code is invalid.	The commodity code is not one of the approved commodity codes.
404	CMR-10016	Not Found: The cart/order ID or the cart/order was not found.	Either the cart/order does not exist or the app does not have access to the cart/order. Can also appear with regard to subscriptions.
404	CMR-10017	Not Found: The user ID is not valid.	The user does not exist in the system. (Not a format issue.)
404	CMR-10038	Not Found: The subscription id is invalid or the subscription was not found.	Either the subscription does not exist or the app does not have access to the subscription.
404	CMR-10039	Not Found: The product code is invalid or the subscription with the given product code was not found.	Either the product code does not exist or developer does not have access to this subscription with the given product code.
406	CMR-10020	Not acceptable.	The message format requested for the client response is not supported.
409	CMR-10021	Conflict: Maximum ordertotal is reached.	The order total exceeds 50,000 USD (that is, the total is equal to or greater than 50,000.01 USD or 41,000.01 EUR or 32,000.01 GBP).
409	CMR-10022	Conflict: The maximum line item number is reached.	The number of line items exceeds the 100 line item limit.
409	CMR-10023	Conflict: Status of cart/order prevents the requested action.	Occurs if: (1) Cart is ordered then a delete request is submitted. (2) Cart is ordered then an update request is submitted. Can also appear with regard to subscriptions.
409	CMR-10024	Conflict: The maximum length of the line item is exceeded.	The line item name exceeds the 100 character limit.
409	CMR-10040	Conflict: Status of subscription prevents the requested action.	Occurs if the subscription is completed, deleted, or has an error status like: billerror or errordone.
409	CMR-10041	Conflict: Activation must occur with 24 hours of creation.	The requested activation is past the 24-hour time window since the original POST Subscription call.
409	CMR-30650	Conflict: Minimum purchase price is not reached.	The purchase price is below the supported minimum price.
409	CMR-60061	Conflict: Request of a refund past the date allowed for refunding.	Orders have a limited number of days where a refund can be requested. The request for a refund is past this date.
409	CMR-60062	Conflict: Request of a refund before the order has finished processing.	Purchases must completely process before a refund can be requested. Typical processing time is between 1 hour and 24 hours.
415	CMR-10030	Unsupported Media Type.	The message format from the client is currently not supported.

Legal Information

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.

A "Mission Critical Application" is any application in which failure of the Intel Product could result, directly or indirectly, in personal injury or death. SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH MISSION CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES, SUBCONTRACTORS AND AFFILIATES, AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF EACH, HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE ATTORNEYS' FEES ARISING OUT OF, DIRECTLY OR INDIRECTLY, ANY CLAIM OF PRODUCT LIABILITY, PERSONAL INJURY, OR DEATH ARISING IN ANY WAY OUT OF SUCH MISSION CRITICAL APPLICATION, WHETHER OR NOT INTEL OR ITS SUBCONTRACTOR WAS NEGLIGENT IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL PRODUCT OR ANY OF ITS PARTS.

Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined". Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.

The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.

Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.

Intel, the Intel logo, and Intel Identity Services are trademarks of Intel Corporation in the U.S. and/or other countries.

* Other names and brands may be claimed as the property of others.

Copyright © 2013-2014, Intel Corporation. All rights reserved.