Purchases

Entry Point: /purchases/{scope}

A purchase is a receipt of an executed order. A Purchase lists the order’s total cost, purchase date, purchase status (COMPLETE or FAILED), tax paid, paymentmeans, which lists the billing and shipping details as well as customer’s paymentmethods, and line items, which are lists of the items the customer purchased.

Each time customers make successful purchases, Cortex API records them in its database. Using the purchases resource, client developers can retrieve the customer’s purchase history, which allows customers to inspect their previous purchases, check for correctness, and track the purchase’s status. Cortex API records each successful purchase and the last failed purchase. Cortex API does not track each failed purchase, it only records the last failed purchase. Once the purchase completes, the failed purchase is removed from the record and a successful purchase is recorded.

Purchase line items are collections of items the customer purchased. Each line item can contain one or more of the same item, but will not have two different items. For example, one line item can have 7 Rock-Star t-shirts or one Rock-Star t-shirt, but it won’t have one Rock-Star t-shirt and a Song track. The Song track and t-shirt would be in separate line items.

The Paymentmeans resource is responsible for recording a purchase’s billing details, such as a customer’s billing address and paymentmethod

Read Purchase

Retrieve a customer’s purchase.

Workflow

1. Start with purchases
2. GET the link with rel: element
3. Render the response

Response Fields

Type: purchases.purchase

Name	Description	Type
purchase-number	Purchase number associated with the purchase. This is the reference customers use if they need to communicate with the store’s customer service representative.	string
status	Indicates the status of the purchase. The following are possible status values: IN_PROGRESS - The purchase is being processed, COMPLETED - The purchase is processed, CANCELLED - The purchase is cancelled.	string
monetary-total	The total cost paid for the purchase, including taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
taxes	The taxes for the purchase	array
title	The name of the tax.	string
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
tax-total	The total amount of tax paid for the purchase.	object
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
purchase-date	The date on which the purchase was made.	object
value	The millisecond value of the date in Epoch time.	long
display-value	The formatted date value to display on the client application.	string

Read Purchase Billing Address

Read the billing address for the purchase.

Workflow

1. Start with purchase
2. GET the link with rel: billingaddress
3. Render the response

Response Fields

Type: addresses.address

Name	Description	Type
name	The customer name.	object
given-name	The person’s given name.	string
family-name	The person’s family name.	string
address	The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.	object
street-address	The street address.	string
extended-address	Extra field for address information. This field is optional.	string
locality	The city name.	string
region	Valid region codes for this field can be retrieved using the Geographies Resource.	string
postal-code	Postal code or zip code.	string
country-name	Valid country codes for this field can be retrieved using the Geographies Resource.	string
phone-number	Phone number	string
organization	The organization	string

Read Purchase Form

Read the purchase form to complete the purchase. Like the order resource, the purchase form may have Needinfo messages. Needinfos identify a condition that must be satisfied before a transaction can complete. Needinfos link to a selector where the customer can select the missing condition. After the Needinfos are satisfied, the order can be submitted to a purchase. For a list of messages that can appear on the order, see needinfo-messages in the Structured Messages topic.

Workflow

1. Start with order
2. GET the link with rel: purchaseform
3. Render the response

Create Purchase

Submit the purchase form to complete the purchase.

Workflow

1. Start with create-purchase-form
2. Fill out the form
3. POST the form using the link with rel: submitorderaction

Read Purchase Lookup Form

Retrieve the purchase lookup form.

Workflow

1. Start with lookups
2. GET the link with rel: purchaselookupform
3. Render the response

Response Fields

Type: purchases.purchase-number

Name	Description	Type
purchase-number	The purchase number.	string

Lookup Purchase By Number

Look up a purchase by the purchase number.

Workflow

1. Start with purchase-lookup-form
2. Fill out the form
3. POST the form using the link with rel: purchaselookupaction

Request Fields

Type: purchases.purchase-number

Name	Description	Type
purchase-number	The purchase number.	string

Read Purchase Line Item

Retrieve a purchase’s line item, which includes details on the item that was purchased such as item name, quantity purchased, and cost.

Workflow

1. Start with purchase
2. GET the link with rel: lineitems
3. GET the link with rel: element
4. Render the response

Response Fields

Type: purchases.line-item

Name	Description	Type
name	The name of the item that was purchased.	string
quantity	The number of items that were purchased.	integer
configuration	The Fields associated with the purchase line item (Dictionary of String/Strings)	object
line-extension-tax	The tax paid for the purchased item(s).	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-amount	The purchase price of the item(s), excluding taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-total	The total amount paid for the item(s), including taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string

Read Purchase Line Item Option

Read the option for the item purchased by the customer.

Workflow

1. Start with purchase-line-item
2. GET the link with rel: options
3. GET the link with rel: element
4. Render the response

Response Fields

Type: purchases.option

Name	Description	Type
name	The name of the item option.	string
display-name	The localized name of the item option, intended for display in the client application.	string
selected-value-id	The id of the selected value.	string
option-id	The id of the option.	string

Purchase Line Item Option Value

The purchase line item option value.

Workflow

1. Start with purchase-line-item-option
2. GET the link with rel: value
3. Render the response

Response Fields

Type: purchases.value

Name	Description	Type
name	The name of the item option.	string
display-name	The localized name of the option name, intended for display in the client application.	string

Purchase Line Item Components

Read the component for the item purchased by the customer.

Workflow

1. Start with purchase-line-item
2. GET the link with rel: components
3. GET the link with rel: element
4. Render the response

Response Fields

Type: purchases.line-item

Name	Description	Type
name	The name of the item that was purchased.	string
quantity	The number of items that were purchased.	integer
configuration	The Fields associated with the purchase line item (Dictionary of String/Strings)	object
line-extension-tax	The tax paid for the purchased item(s).	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-amount	The purchase price of the item(s), excluding taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-total	The total amount paid for the item(s), including taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string

Read Dependent Purchase Line Item

Read a dependent purchase line item.

Workflow

1. Start with purchase-line-item
2. GET the link with rel: dependentlineitems
3. GET the link with rel: element
4. Render the response

Response Fields

Type: purchases.line-item

Name	Description	Type
name	The name of the item that was purchased.	string
quantity	The number of items that were purchased.	integer
configuration	The Fields associated with the purchase line item (Dictionary of String/Strings)	object
line-extension-tax	The tax paid for the purchased item(s).	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-amount	The purchase price of the item(s), excluding taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-total	The total amount paid for the item(s), including taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string

Read Parent Purchase Line Item

Read a parent purchase line item.

Workflow

1. Start with purchase-line-item
2. GET the link with rel: parent
3. Render the response

Response Fields

Type: purchases.line-item

Name	Description	Type
name	The name of the item that was purchased.	string
quantity	The number of items that were purchased.	integer
configuration	The Fields associated with the purchase line item (Dictionary of String/Strings)	object
line-extension-tax	The tax paid for the purchased item(s).	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-amount	The purchase price of the item(s), excluding taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string
line-extension-total	The total amount paid for the item(s), including taxes.	array
currency	The currency the cost is in.	string
amount	The decimal value of the cost.	decimal
display	Formatted currency string that can be displayed on the client application.	string

Read Paymentmean

Read a payment mean from a list of payment means.

Workflow

1. Start with purchase
2. GET the link with rel: paymentmeans
3. GET the link with rel: element
4. Render the response