Campaign Integration Guide
Best practices for integrating external campaigns and funnels to 29 Next
These best practices are suggestions to offer the best performance, flexibility, and ease of use in leveraging 29 Next’s features, and will reference API methods and structures.
For most externally-hosted campaigns, use the
orders_createAPI call to create a new order, create a new customer, and process the order’s payments in a single call. If your campaign flow requires that a customer be created first, or that a cart be populated with products before the checkout and order placement event, you may use users_create and/or carts_create APIs.
When creating an order using the orders_create API, specify products as line items by sending the
stockrecord_id, rather than using the optional
The advantages of using this approach are:
- Each stock record already has a specific currency associated to it, so there’s no need to define the currency separately.
- SKU codes can be changed manually by admin users from time to time. Therefore a campaign using SKUs on the API could break upon such changes, whereas a stockrecord_id cannot be changed once created.
If you have not yet created a customer (user), there is no need to use a separate API call -
orders_createwill create the customer at the same time as creating a new order.
The unique customer values are email address and phone number. If you attempt to create an order for a new customer using an existing customer’s email address or phone number, an error response will be returned.
If you are creating an order for a customer (user) that already exists, either by having signed up on the storefront, or by the users_create API, you can reference them by
idhere. You will then not need to define addresses. In that case, instead set parameters
use_default_billing_addressto = true.
The terms user and customer are used interchangeably in 29 Next.
shipping_codecorresponding to the store’s configured shipping methods, which will apply the corresponding shipping cost to the order.
Define source attribution values according to the order's marketing source, such as utm_(values), affiliate, subaffiliate1, and so on.
It is recommended to pass a
funnel idfor each unique campaign, which will roll up to various reports in 29 Next. Create each unique Funnel in the Dashboard Funnels section, even for externally hosted campaigns, to assign an ID to each funnel for use in this source attribution field. Again, this helps to attribute the unique source funnel to reports for easier data egmentation and analytics.
orders_createAPI calls, you should pass the Everflow click ID as the
everflow_transaction_idinto source attribution metadata. The system will recognize that value and pass it back to the Everflow postback URL on order events.
It is best practice to always include a store’s
payment_return_urlin API calls under the
- 3DS2 flows rely on this return URL to process transactions. For transactions that don’t require the
payment_return_url(e.g. standard bankcard transactions) there is no harm in including it in the API request anyway.
- Paypal, Klarna, and other local payment methods, also require a redirect at checkout. Conceptually, implementing these methods is exactly the same.
When creating orders using
orders_createAPI for stores with multiple bankcard payment providers, the best practice is to specify a gateway group rather than a single payment gateway.
payment_detailsspecify a payment_gateway_group to use to process the payment on the order.
orders_add_line_itemsAPI call to add post-checkout upsells to a customer’s order.
This approach of adding items to the parent order, rather than creating separate new orders, has the advantage of consolidating various upsells taken in the same shopping session into a single Order.
Adding line items to the existing order will automatically attempt billing on the original order’s approved payment method.
- For bankcard transactions, this simply reattempts the card (token) used on the initial order.
- PayPal requires the account to have Reference Transactions enabled (Express API) to allow for one-click post-checkout upsells to be processed without interruption to the user. PayPal must approve this for each PayPal account via a support request. Once approved, the setting is easily enabled via the Dashboard Enable Reference Transactions
- Other APMs may or may not support one-click upsells
Offers are typically used to create discounted pricing for product bundles that meet a certain size or configuration, and to achieve custom price points in your checkout. For example buy 3 get 2 free, buy 2 get 1 free, or to qualify certain purchases for additional incentives, like buy 5 to get free shipping.
- Offers applied to orders will be reflected on the discount line of a customer’s order summary
- Adding an Offer ID or a Voucher (Coupon) Code to
orders_createis optional, but it is the recommended approach when selling bundles, to properly reflect discounts and incentives in the sales policy of the store.
The same concepts apply. Coupons and Promo codes are referred to as
voucherson the API.
It’s important to understand that Vouchers act as containers for Offers. Multiple Offers can be combined and applied to a single Voucher (Coupon Code), which opens the door to greater flexibility in pricing and incentives.
- Coupons allow you to test and validate your pricing configuration on the storefront checkout prior to creating orders over the API.
- Coupons therefore allow you to set the prices and offers to apply, prior to external campaigns or funnel integrations being completed.
Optionally use the
users_createAPI to create a customer and address records before creating a new order. A customer in 29 Next is referred to as a user on the Admin API.
- Once a customer is created, you can reference them simply by
idon a subsequent
orders_createcall. Setting billing and shipping addresses to default (as collected when the customer was created) can bypass friction in the checkout process.
Optionally use the
carts_createAPI to create a cart, including line items, offers, coupons to apply, and marketing source attribution.
- Captures the full context of a customer before they check out, to allow for re-marketing options in case of a checkout abandonment or a payment attempt decline.
- Allows a preview of all pricing and dynamic sales taxes applied to a cart, pending the processing of an order.
Use Test Orders to validate your integration, pricing, source attribution, and so on.
- Test orders are not included in sales and transactions reporting
- Test orders are not automatically sent to fulfillment partners for shipping
- Test orders are excluded from order exports
- Test orders do not perform gateway transactions and are always successful