This endpoint is used to programmatically conduct Shoppable checkouts.
NOTICE: All use of Shoppable's Checkout API requires a specific API license agreement. If you are interested, please contact your customer success manager if you have one. If you don't, please fill out this form here and we'll be in touch within one business day or less.
Shoppable Checkout Call
Overview
This endpoint is used to programmatically conduct Shoppable Universal checkouts. Users will send over information regarding the products (UPC, merchant, price, etc) as well as PII (address(es) and credit card information) and receive an order number back if their request is successful, or an error message if not.
API EndPoint
POST: https://cloud.shoppable.com/checkout
Authentication
Authentication is done with two headers in the request header. Both bearer token and x-shoppable-secret will be provided to you by your Customer Success Manager at Shoppable.
Request Headers
"Authorization": “Bearer <Bearer token that will be provided by shoppable>”,
"x-shoppable-secret": “<Shoppable Secret will be provided by shoppable>”
"Content-Type": "application/json"
Request Header authorization parameters when generating your request along with context
|
Name |
Description |
|
Authorization |
Unique token that allows access to authorized users to make calls against the Product API. |
|
|
Unique identifier string that together with the authorization bearer, validates the bearer token |
Request Body
Requests must be in application/json format and must contain the following variables.
|
Name |
Description |
|
cartDetails (object) |
Object with all information pertaining to the cart (items needed to be checked out, email, etc) |
|
shippingDetails (object) |
Object containing all shipping information |
|
billingDetails (object) |
Object containing all billing information |
|
paymentDetails (object) |
Object containing all payment information for the user . |
cartDetails
|
Name |
Description |
|
email (string) |
The email for the user to send a confirmation email |
|
sendConfirmationEmail (boolean) |
Boolean value to indicate whether to send a confirmation email |
|
marketingOptIn (boolean) |
Whether to opt in to the brand's marketing emails, using the email provided |
|
substitutionOptIn (boolean) |
Whether to agree to Shoppable's substitution policy |
|
lineItems (array) |
Array of objects for items to be added to the cart (see below) |
lineItems
|
Name |
Description |
|
upc (string) |
UPC for the product |
|
merchantId (string) |
The specific Object Id of the merchant. This is required for merchant selection |
|
price (number) |
Number for the price. Must be less than or equal the listed price |
|
quantity (string) |
The number of items requested for the product |
shippingDetails
|
Name |
Description |
|
firstName (string) |
First name of the person that this item is being shipped to |
|
lastName (string) |
Last name of the person that this item is being shipped to |
|
address1 (string) |
Street of the person that this item is being shipped to |
|
address2 (string) |
Optional parameter if the user resides at a building with multiple units |
|
city (string) |
City of the person that this item is being shipped to |
|
state (string) |
Two letter abbreviation of the state of the person that this item is being shipped to |
|
country (string) |
Two letter ISO code of the country that this item is being shipped to (currently only the United States is supported) |
|
zipCode (string) |
5 digit zip code of the person that this item is being shipped to |
|
phoneNumber (string) |
Phone number of the person that this item is being shipped to |
billingDetails
|
Name |
Description |
|
firstName (string) |
First name of the person that this item is being billed to |
|
lastName (string) |
Last name of the person that this item is being billed to |
|
address1 (string) |
Street of the person that this item is being billed to |
|
address2 (string) |
Optional parameter if the user resides at a building with multiple units |
|
city (string) |
City of the person that this item is being billed to |
|
state (string) |
Two letter abbreviation of the state of the person that this item is being billed to |
|
country (string) |
Two letter ISO code of the country that this item is being billed to (currently only the United States is supported) |
|
zipCode (string) |
5 digit zip code of the person that this item is being billed to |
paymentDetails
|
Name |
Description |
|
nameOnCard (string) |
Full name on the card |
|
cardNumber (string) |
16 digit card number |
|
expireMonth (string) |
2 digit month of expiration for the card |
|
expireYear (string) |
4 digit year of expiration for the card |
|
cvv (string) |
CVV of the card |
{
"cartDetails": {
"email": "email@gmail.com",
"sendConfirmationEmail": false,
"marketingOptIn": true,
"substitutionOptIn": true,
"lineItems": [
{
"upc": "00090127683996",
"merchantId": "62a0b5555ce2f83f392eca85",
"price": 20.0,
"quantity": 1
}]
},
"shippingDetails": {
"firstName": "First",
"lastName": "Last",
"address1": "Address 1",
"address2": "Address 2",
"city": "City",
"state": "NY",
"country": "US",
"zipCode": "00000",
"phoneNumber": "1234567890"
},
"billingDetails": {
"firstName": "First",
"lastName": "Last",
"address1": "Address 1",
"address2": "Address 2",
"city": "City",
"state": "NY",
"country": "US",
"zipCode": "07030"
},
"paymentDetails": {
"nameOnCard": "Last",
"cardNumber": "4111111111111111",
"expireMonth": "02",
"expireYear": "2025",
"cvv": "111"
}
}
Response
On a successful call you will receive the following data.
|
Name |
Description |
|
number |
Object containing the order number, if successful |
|
error (number) |
If there were any errors during the checkout |
|
message (string) |
If there were errors, this message will display what the error was |
{
"number": {
"number": “R147776576”
},
"error": false,
“message”: “”
}
NOTE:
The Shopper's order will be processed with whatever Merchant you send in the payload to Shoppable.
If you want to optimize which Merchant you recommend to the Shopper based on prices, you could use Shoppable's Product API to build that on your experience.