⚡
API Integration Guide
Best practices for integrating external website funnels to 29 Next
This document is intended to guide third party developers on integrating custom web sites or campaigns to 29 Next via the Admin API.
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_create API 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.orders_createUse this API call to create orders, customers, and payments in a single call.
When creating an order using the orders_create API, specify products as line items by sending the
stockrecord_id, rather than using the optional sku and currency parameters.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.
Using
sku and currency for line items when creating orders is a valid practice, but the recommended best practice is to instead use stockrecord_id
More on Stock RecordsIf you have not yet created a customer (user), there is no need to use a separate API call -
orders_create will 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.
When creating a new order, you should always make sure to specify the user’s
language to ensure that customers receive notifications in their expected language.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
id here. You will then not need to define addresses. In that case, instead set parameters use_default_shipping_address and use_default_billing_address to = true.The terms user and customer are used interchangeably in 29 Next.
Specify a
shipping_code corresponding to the store’s configured shipping methods, which will apply the corresponding shipping cost to the order.All orders require a shipping code to be specified. You can override the corresponding shipping method's price by passing a custom
shipping_price in your API call.
More on shipping methodsDefine 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 id for 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 segmentation and analytics.Everflow is integrated into 29 Next for server-to-server postbacks and meta-source attribution mapping.
For
orders_create API calls, you should pass the Everflow click ID as the everflow_transaction_id into source attribution metadata. The system will recognize that value and pass it back to the Everflow postback URL on order events."attribution": {
"metadata": {
"everflow_transaction_id": "string"
}
}
It is best practice to always include a store’s
payment_return_url in API calls under the payment_details section- 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_create API for stores with multiple bankcard payment providers, the best practice is to specify a gateway group rather than a single payment gateway. Under
payment_details specify a payment_gateway_group to 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.
Use the
orders_add_line_items API 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.
This flows up to the Order Confirmation email notification that the customer receives, and the summary of the order on the Success Page, where the customer can view the entire contents of the 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
- If PayPal has not enabled Reference Transactions for the PayPal account, then one-click upsell attempts will return an error message. More on PayPal one-click upsells.
- 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
price parameter on your orders_create call, 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.
If an Offer ID is passed on the Admin API in an
orders_create call, but the order contents do not align or otherwise qualify for the Offer’s conditions, the order will be created without applying the Offer. The standard price for the given products will instead be applied.The same concepts apply. Coupons or Promo codes are referred to as
vouchers on 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.
Advantages
- 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_create API 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.Advantages:
- On campaigns or marketing funnel flows where the customer inputs their name, addresses, and details on a page before the checkout page, you can capture the lead data
- Once a customer is created, you can reference them simply by
idon a subsequentorders_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_create API to create a cart, including line items, offers, coupons to apply, and marketing source attribution.Advantages:
- 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 created sync to the Dashboard view of the Cart under the Customer Details View. Admin or support staff can manually enter, modify, and checkout the cart on the customer’s behalf, or send the customer a custom Check Out Link upon finalizing the cart's contents.
Combining
users_create with carts_create can 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
From the Orders List View you can choose Actions > Delete Test Orders to remove test orders from the store's orders list.
Last modified 2mo ago