Making purchases

Prequisites

Before you get started, you should have:

an API key
an onboarded customer (check out the Customer onboarding guide if you haven't added your customer onboarding flow yet)

This integration guide will use cURL syntax, but you can find syntax for other common libraries and languages in the API reference.

Overview

A PurchaseIntent guides you through the process of making a purchase for your customer. We recommend that you create exactly one PurchaseIntent for each purchase attempted in your system.

A PurchaseIntent goes through multiple states in its lifetime as you collect required information from your customer and ultimately execute the purchase:

Identify product to purchase

The first step is identifying the specific product to purchase. We provide 2 APIs for exploring eligible product data:

Getting variant attributes

Products may have product variants, which are different versions or models of the same product. For example, in the case that a t-shirt comes in different sizes and colors - one variant may be {Size Small, Color Red}, while another is {Size Medium, Color Blue}.

To explore the variant attributes of a product, use the VariantData API:

curl --request GET \
  --url 'https://api-agent.useelevate.dev/v1/variant_data?product_url=<product_url>' \
  --header 'Authorization: Bearer YOUR_KEY_HERE'

Getting product data

To retrieve product information, including whether a specific product is eligible for autonomous checkout, use the ProductData API. This API will return realtime data about the product, such as the price, shipping cost, and availability (in stock or not). Note: this API only looks at the specific product variant requested via the product URL, availability of alternative variants would have to be checked separately.

curl --request GET \
  --url 'https://api-agent.useelevate.dev/v1/product_data?product_url=<product_url>' \
  --header 'Authorization: Bearer YOUR_KEY_HERE'

Creating the PurchaseIntent

Once the user has selected the item they want to purchase, the first step is creating the PurchaseIntent with the create endpoint. You must call this API with the URL of the specific variant for purchase.

curl --request POST \
  --url https://api-agent.useelevate.dev/v1/purchase_intents \
  --header 'Authorization: Bearer YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cus_my-test-customer",
  "product_url": "https://www.test-useelevate.dev/p=success",
  "livemode": true,
}
'

Creating the PurchaseIntent will perform an eligibility check for autonomous checkout. After the eligibility check, the PurchaseIntent may be in one of the following states:

INELIGIBLE: If the PurchaseIntent is ineligible for autonomous checkout, its state will transition to ineligible_for_automatic_checkout. If a PurchaseIntent is ineligible for autonomous checkout, no further action can be taken on it.
READY TO BE CONFIRMED: If the PurchaseIntent is eligible for autonomous checkout, and there are no choices to be made (e.g. no product variants to choose and only one possible option for shipping), its state will transition to requires_confirmation. We will provide you with metadata about the product at this point, such as price and shipping cost, which you can show to the customer before confirmation. In this case, the next step is Confirming the PurchaseIntent.

You can create a PurchaseIntent in either livemode (livemode = true) or testmode (livemode = false). A PurchaseIntent created in testmode will not attempt to initiate a real purchase. You must set livemode to true to execute a real purchase. You can only create a livemode PurchaseIntent with a livemode Customer, and vice versa.

We recommend showing the price and other costs to your user before confirmation. This may include:

amount_subtotal: The item price before other costs.
tax_inclusive: True if tax is included in the item price, or false if it is not. If tax_inclusive is false, we recommend showing some messaging to user such as "Tax will be calculated at checkout." or "${amount_subtotal} plus tax".
amount_shipping: The shipping price.
estimated_amount_total: The item price before costs that are calculated at checkout (e.g. tax).

Confirming the PurchaseIntent

If the PurchaseIntent is eligible for autonomous checkout and its state is requires_confirmation, it is ready to be confirmed via the confirm endpoint. Confirming the PurchaseIntent will attempt to execute the purchase and charge the customer's payment method on file.


Note: Upon confirming, the purchase will be executed and customer's payment method charged. We highly suggest confirming with your customer (e.g. via UI) to confirm they want to make the purchase before executing this step.

When confirming the PurchaseIntent, you must pass in the total price the customer expects to pay. You should pass in the total price you showed to the customer when they made the purchase decision (per above, we recommend using the expected_estimated_amount_total price we give you in the initial eligibility check).

curl --request POST \
  --url https://api-agent.useelevate.dev/v1/purchase_intents/:id/confirm \
  --header 'Authorization: Bearer YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expected_estimated_amount_total": 2332
}
'

If the price expectation matches, we move ahead to executing the purchase, and the state will transition to initiated while the purchase is in progress.

There are a few key errors you should handle if the purchase confirmation fails:

Title	Description
expected_price_mismatch	The expected price you passed us doesn't match the price we have on file. To be safe, we do not move forward with the purchase.
price_changed	The price we gave you has changed since this PurchaseIntent was initialized. This is rare if the PurchaseIntent is created and confirmed within a short timeframe.
item_no_longer_available	Since you initially created this PurchaseIntent, the item is no longer available (e.g. out of stock). This is rare if the PurchaseIntent is created and confirmed within a short timeframe.
customer_account_expired	The customer's account authentication has expired. You should re-direct them to re-authenticate if they want to continue making autonomous checkouts.
purchase_execution_error	This may include a payment error (e.g. the customer's card was declined) or another issue with the execution flow of the purchase. You should fall back to non-autonomous checkout.


Note: Errors follow the HTTP Problem Details Standard so this error appears in the "Title" field.
Testing: You can use our test scenarios to deterministically trigger these errors and test your integration.

If confirmation of the PurchaseIntent fails for any of these reasons, we cancel it instead of executing the purchase. You should create a new PurchaseIntent if you want to try again with updated information.

[Optional] Canceling the PurchaseIntent

If you want to cancel the PurchaseIntent and prevent any attempts at purchasing (for example, because your customer has changed their mind about the purchase), you can cancel the PurchaseIntent with the cancel endpoint.

curl --request POST \
  --url https://api-agent.useelevate.dev/v1/purchase_intents/:id/cancel \
  --header 'Authorization: Bearer YOUR_KEY_HERE'

Canceling the PurchaseIntent is irreversible. If you accidentally cancel a PurchaseIntent you want to attempt again, please create a new one.

[Optional] Retrieving the PurchaseIntent

You can also retrieve existing PurchaseIntents with the retrieve endpoint

curl --request GET \
  --url https://api-agent.useelevate.dev/v1/purchase_intents/:id \
  --header 'Authorization: Bearer YOUR_KEY_HERE'