Purchases

Entry Point: /purchases/{scope}

A purchase is a receipt of an executed checkout. A purchase contains the order’s total cost, purchase date, purchase status (COMPLETE or FAILED), tax paid, paymentinstruments, 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 or account’s purchase history. Both successful purchases and failed purchase attempts are returned.

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.

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 Created By

Read the buyer who initiated the purchase.

Workflow

1. Start with purchase
2. GET the link with rel: created-by
3. Render the response

Response Fields

Type: purchases.creator

Name	Description	Type
user-email	Email address of the user who created the purchase.	string
user-full-name	Full name of the user who created the purchase.	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	The region name. A region typically corresponds to a province or a state of a country.	string
postal-code	Postal code or zip code.	string
country-name	The country name.	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 Look Up Form

Retrieve the purchase look-up 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

Lookup 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 Items

Retrieve a list of purchase line items.

Workflow

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

Read Paginated Purchase Line Items

Retrieve a list of paginated purchase line items.

Workflow

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

Read Paginated Line Items Paginator

Retrieve a paginator form to configure line items pagination.

Workflow

1. Start with paginated-purchase-line-items
2. GET the link with rel: paginator
3. Render the response

Response Fields

Type: purchase.purchase-line-item-paginator

Name	Description	Type
size	Page size. Number of line items on a page.	integer

Read Purchase Line Item

Retrieve a purchase’s line-item including details on the purchased item, 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