Campaigns Admin API

The Admin API gives you full setup and management of campaigns without going through the dashboard. Create a campaign, add its packages, offers, and shipping methods, read back the API key your funnel pages need, and update any of it later as your catalogue and pricing change. Everything is available over the API, so an AI agent can drive the entire campaign lifecycle for you.

It also pays off once you run more than a handful of campaigns:

• Stand up a campaign per market or per test, each with its own currency and payment methods
• Update every campaign that sells a product after you reprice or discontinue it
• Push a new price to one currency and let the rest recalculate from your default

Permissions

Campaign endpoints are authorized by OAuth scope on the app making the request.

Additional scopes required:

See Admin API permissions for the full scope list and Admin API → Getting Started for creating an OAuth app.

Campaign Provisioning Flow

Standing up a campaign end to end is a 4 step process:

1. Retrieve the payment gateway group using the gatewayGroupsList endpoint to get its id and the payment methods it supports.
2. Create the campaign using the campaignsCreate endpoint.
3. Add a package for each sellable item using the campaignsPackagesCreate endpoint.
4. Read the campaign's api_key from the create response and configure your funnel pages with it.

Create a Campaign

Below is an example API call to create a campaign for a US English funnel that also accepts CAD. name, currency, language, and payment_gateway_group_id are required, everything else is optional.

{
  "name": "Spring Widget Launch US", // internal reference name
  "currency": "USD", // default currency for orders on this campaign
  "language": "en", // preferred customer language
  "payment_gateway_group_id": 4, // from gatewayGroupsList
  "additional_currencies": ["CAD"], // currencies supported beyond the default
  "available_payment_methods": ["card_token", "paypal"], // codes from gatewayGroupsList
  "available_express_payment_methods": ["apple_pay"], // express codes from gatewayGroupsList
  "available_shipping_countries": ["US", "CA"], // ISO 3166-1 alpha-2 codes
  "statement_descriptor": "WIDGETCO" // shown on the customer's card statement
}

The response returns the campaign id you use for every package call, and the api_key your funnel pages authenticate with.

The payment methods you enable have to be ones the gateway group supports. gatewayGroupsList returns each group on the store with its id, available_payment_methods, available_express_payment_methods, and available_currencies.

Add Packages to a Campaign

A package is the campaign's sellable reference to a product or variant, and its id is what your funnel markup passes as data-next-package-id. Only name and product_id are required.

{
  "name": "Widget Single", // package name
  "product_id": 184, // product linked to the package
  "product_variant_ids": [512], // product variants linked to the package
  "price": "49.95" // price per product variant unit
}

Create a Subscription Package

Subscription packages carry a recurring interval and a separate recurring price. interval accepts day or month.

{
  "name": "Widget Monthly Refill",
  "product_id": 184,
  "product_variant_ids": [512],
  "price": "49.95", // charged on the initial order
  "price_recurring": "39.95", // charged on each renewal
  "interval": "month", // day or month
  "interval_count": 1 // renew every 1 month
}

Repricing Across Currencies

campaignsPackagesCreate takes a single price and price_recurring. campaignsPackagesPartialUpdate takes a prices array with one entry per currency, and currencies you leave out are not changed.

{
  "prices": [
    {
      "currency": "USD",
      "price": "44.95",
      "price_recurring": "34.95"
    }
  ],
  "recalculate_prices": true // derive the other currencies from the default currency price
}

With recalculate_prices set to true, every currency you did not list is recalculated from the campaign's default currency price. Left false (the default), only the currencies you passed change.

Add Offers to a Campaign

An offer discounts the order once its condition is met. name, condition, and benefit are required. The condition decides which packages and what quantity trigger the offer, and the benefit sets the percentage off. An offer applies automatically at checkout unless it is a code offer (offer_type of voucher).

{
  "name": "Buy 2 Save 30%", // unique within the campaign
  "condition": {
    "type": "count", // any, or count for a minimum quantity
    "value": 2, // minimum package quantity, required when type is count
    "package_ids": [2231] // package ids from campaignsPackagesCreate, or send all_packages: true
  },
  "benefit": {
    "type": "package_percentage", // package_percentage, shipping_percentage, or order_percentage
    "value": "30.00", // percentage off
    "price_rounding": "0.95" // round each discounted unit price to XX.95, omit for no rounding
  }
}

Create one offer per quantity tier to control the price the customer pays at each quantity. See Concepts → Offers for a worked example.

Use a code offer for discounts on upsell, downsell, and exit-pop pages. Automatic offers run only at checkout, so a code offer is the only way to discount an upsell or an exit-pop incentive. Set offer_type to voucher to create one. The code offer applies when the customer enters its code, or when your page submits the code through the vouchers array on the cart, order, or upsell-create request (see Campaigns API → Offers). Set all_packages to true with an any condition to make it valid on anything in the cart.

{
  "name": "Upsell 10% Off",
  "offer_type": "voucher", // offer (automatic) or voucher (code offer, code required)
  "code": "UPSELL10", // required when offer_type is voucher, submit it from the upsell or exit-pop page
  "condition": {
    "type": "any", // no quantity requirement
    "all_packages": true // apply to all current and future packages
  },
  "benefit": {
    "type": "order_percentage",
    "value": "10.00"
  }
}

Add Shipping Methods to a Campaign

A campaign shipping method links a shipping method already configured on the store to this campaign at a campaign specific price. Both shipping_method and price are required. name is populated automatically from the code you pass.

{
  "shipping_method": "default-shipping", // code from the store's configured shipping methods
  "price": "4.95" // price in the campaign's default currency
}

Every other currency configured on the campaign is populated automatically through forex conversion.

To change prices later, campaignsShippingMethodsPartialUpdate takes the same prices array and recalculate_prices flag as packages, and currencies you leave out are not changed.

{
  "prices": [
    { "currency": "USD", "price": "5.95" }
  ],
  "recalculate_prices": true // convert the other currencies from the price above
}

Find Campaigns to Act On

campaignsList is cursor paginated and filterable. Follow next in the response until it is null.

{}

Audit Packages Against Your Catalogue

campaignsPackagesList filters on name, product_name, and product_sku, so you can find every package on a campaign that sells a discontinued SKU.

{}

Each package returns product_purchase_availability (available or unavailable) and product_inventory_availability (in_stock, low_stock, out_of_stock, or untracked). Check these to catch packages pointing at products customers can no longer buy.

Retire a Campaign or Package

campaignsDestroy deletes a campaign's settings and campaignsPackagesDestroy removes a single package.

Endpoints

Full request and response detail lives in the Admin API reference.

Campaigns

Offers

Packages

Shipping Methods