Campaigns API
Campaigns App opens up new possibilities for frontend developers to easily create complex external campaign flows using Javascript, no backend server-side integration required.
The Campaigns App provides an easy to use CORS enabled API that follows the best practices for integrating to our Admin API for an External Checkout Flow.
Campaigns App API
Campaigns App API is available through the Campaigns App. To enable, install the Campaigns App in your store from the Apps view.
See Campaigns API ReferenceCampaigns Overview
A "campaign" is a defined set of packages and payment rules as a backend for the HTML/JS webpages of a campaign (or funnel) frontend. You can easily setup multiple campaigns for different product offers, markets, and A/B testing.
Packages
Each campaign can have multiple "Packages" configured to set quantity based pricing rules for your products. Typically this results in packages such as:
Example Packages
- Package 1 - 1x Widget at 10.00
- Package 2 - 3x Widget at 21.00
- Package 3 - 5x Widget at 30.00
- Package 4 - 1x Widget at 8.00 Recurring Every 30 Days
Package total price needs to be divisible to two digits by the quantity as the total price is sent on a per item level to the store Orders API.
Shipping Options
Campaigns can have custom shipping prices to optimize shipping fees and methods available on your campaign to override the default pricing configured globally in the store.
Example Shipping Methods
- Shipping Method 1 - Default shipping at 7.99
- Shipping Method 2 - Express shipping at 14.99
Getting Started
To get started, create a new campaign with a package mapped to a product in your store. Use the examples below with your Campaign API Key to get started using the Campaigns API.
Create Cart
var payload = {
"user": {
"email": "test@email.com",
"first_name": "John",
"last_name": "Doe"
},
"lines": [
{
"package_id": 1
}
],
"attribution": {
"utm_source": "Example Campaign"
}
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/carts/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
"Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
},
body: JSON.stringify(payload),
});
const result = await response.json()
console.log(result); // Show result in console
Create Order
Creating an order is the core method in an external checkout flow, see the example below to familiarize yourself with the payload data required.
success_url
ExplainedAll orders require a success_url
to handle payments requiring a redirect flow. The success_url
should be the absolute URL of the "Next Page" in your campaign flow. In most cases, this should be your first upsell page, see more below in Adding Upsells on retrieving order details and handling payment methods that support upsells.
var payload = {
"user": {
"email": "test@email.com",
"first_name": "John",
"last_name": "Doe"
},
"lines": [
{
"package_id": 1
},
{
"package_id": 2,
"is_upsell": true
}
],
"shipping_address": {
"first_name": "string",
"last_name": "string",
"line1": "string",
"line4": "string",
"state": "string",
"postcode": "string",
"phone_number": "string",
"country": "string"
},
"billing_same_as_shipping_address": false,
"payment_detail": {
"payment_method": "card_token",
"card_token": "test_card" // See iFrame Payment Form Guide
},
"shipping_method": 1,
"success_url": "https://your-campaign.com/next-page/" // Next Page in Flow
"payment_failed_url": "https://your-campaign.com/decline-flow/" // Optional Decline Page
"attribution": {
"utm_source": "Example Campaign"
}
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/orders/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
"Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
},
body: JSON.stringify(payload),
});
const result = await response.json();
console.log(result); // Show result in console
Bankcard payments require using the iFrame Payment Form and passing the generated card_token
for secure transfer of the payment method details. View a fully functional Demo.
- If response data has a
number
, order was successfully created, you can redirect to the next page. - If response data has a
payment_complete_url
, redirect the user to this page. After payment, user will come back to yoursuccess_url
orpayment_failed_url
.
If an APM redirect flow declines or is canceled, by default the user is redirected back to the HTTP referrer with contexual querystings, ie ?payment_failed=true&payment_method=paypal
.
Pass payment_failed_url
to more explicitly control the decline handling for APM redirect flows.
Adding Upsells
To add an upsell to an existing order, first you should check to see if the order payment method supports_post_purchase_upsells
is True
in the orderRetrieve
response.
const refId = '<YOUR ORDER REF ID>'
const response = await fetch('https://campaigns.apps-staging.29next.com/api/v1/orders/' + refId + '/', {
method: 'GET',
headers: {
'Content-Type': 'application/json',
"Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
}
});
const result = await response.json();
console.log(result); // Show result in console
If the order supports_post_purchase_upsells
, you can add an upsell to an order can be done using the orderUpsellCreate
API endpoint.
const refId = '<YOUR ORDER REF ID>'
var payload = {
"lines": [
{
"package_id": 1
}
]
}
const response = await fetch('https://campaigns.apps.29next.com/api/v1/orders/' + refId + '/upsells/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
"Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
},
body: JSON.stringify(payload),
});
const result = await response.json();
console.log(result);
Order Confirmation
On the order confirmation page, you can retrieve the order details and map the values to your template to show an order summary to the customer.
const refId = '<YOUR ORDER REF ID>'
const response = await fetch('https://campaigns.apps-staging.29next.com/api/v1/orders/' + refId + '/', {
method: 'GET',
headers: {
'Content-Type': 'application/json',
"Authorization": '<YOUR CAMPAIGN API KEY>' // Campaign API Key
}
});
const result = await response.json();
console.log(result); // Show result in console