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
- Start with purchases
GET
the link with rel: element- 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
- Start with purchase
GET
the link with rel: billingaddress- 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.
Workflow
- Start with order
GET
the link with rel: purchaseform- Render the response
Create Purchase
Submit the purchase form to complete the purchase.
Workflow
- Start with create-purchase-form
- Fill out the form
POST
the form using the link with rel: submitorderaction
Read Purchase Lookup Form
Retrieve the purchase lookup form.
Workflow
- Start with lookups
GET
the link with rel: purchaselookupform- Render the response
Lookup Purchase By Number
Look up a purchase by the purchase number.
Workflow
- Start with purchase-lookup-form
- Fill out the form
POST
the form using the link with rel: purchaselookupaction
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
- Start with purchase
GET
the link with rel: lineitemsGET
the link with rel: element- 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
- Start with purchase-line-item
GET
the link with rel: optionsGET
the link with rel: element- 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
- Start with purchase-line-item-option
GET
the link with rel: value- 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
- Start with purchase-line-item
GET
the link with rel: componentsGET
the link with rel: element- 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
- Start with purchase
GET
the link with rel: paymentmeansGET
the link with rel: element- Render the response