API Integration Guide
Best practices for integrating external website 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
Use this API call to create orders, customers, and payments in a single call.
When creating an order using the
orders_createAPI, specify products as line items by sending the
The advantages of using this approach is that there is no need to duplicate Products to handle multi-currency and multi-location selling.
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_createAPI, you can reference them by
idhere. You will then not need to define addresses.
In that case, instead set parameters
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 price to the order.
Orders do not require a shipping code to be specified. If no shipping code is specified on the API, the order's shipping price will default to the lowest priced method available. You can also override a shipping method's price by passing a custom
shipping_pricein your API call, or leave out shipping method entirely and pass a custom
shipping_priceto assign to the order. More on Shipping Methods
It is recommended to pass a
funnel idfor each unique campaign, which will roll up to various reports in 29 Next.
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 in 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, Apple Pay, Klarna, and other wallets and 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_gateway_groupto use to process the payment on the order.
Even if there is only a single payment gateway available for a store, it is recommend to use gateway groups rather than a single payment gateway ID. Gateway Groups can be edited from the Dashboard Payment Settings to add, remove, or alter the weighting of gateways, without changes being required on the external campaign or web site.
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.
The “Order Confirmation Notification Delay” is configurable via Settings > Checkout allowing up to a 10 minute delay on sending Order Confirmation email notifications, to allow time for upsells to be added to the order in the same shopping session.
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 wallets and 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.
An alternative to applying Offers is to use the
priceparameter on your
orders_createcall, which overrides the default product pricing and creates orders with a custom unit price. It's important to note this field defines the line item price, not the overall line total price. For example:
price = 1.99 quantity = 3 line total = 5.97
- 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 or 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.
carts_createcan also be useful on multi-step campaign funnels, to capture the maximum amount of shopper context even when orders are not placed in the same session.
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