Before you get started, you should have:
This integration guide will use cURL syntax, but you can find syntax for other common libraries and languages in the API reference.
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:
The first step is identifying the specific product to purchase. We provide 2 APIs for exploring eligible product data:
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'
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'
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_for_automatic_checkout.
If a PurchaseIntent is ineligible for autonomous checkout, no further action can be taken on it.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).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.
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.
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'